Design Multi-Context Processing Tools as Capabilities, Not Endpoints

A developer warns against mapping MCP tools 1:1 onto REST API endpoints, citing token consumption and context pollution. The author recommends designing MCP tools as capabilities, such as a single manage_user tool instead of seven separate user-related tools, and notes that while dynamic tool discovery is emerging, most clients still load all tool schemas upfront.

One anti-pattern I keep seeing: mapping MCP tools 1:1 onto a REST API. Take a typical user API - createUser, updateUser, getUser, listUsers, deleteUser, getUserPermissions, setUserPermissions. If you map that directly onto MCP tools, you get seven entries in the model’s context window on every request. That starts eating tokens, which will hurt you in the long run - cost and context pollution. That is not what an MCP tool is for. Think of a tool as a capability, not an endpoint. Instead of seven tools, create one manage user tool that handles creation, updates, and permissions internally, then returns a clean summary. In most MCP clients today, every registered tool schema gets loaded into context before your prompt is processed, so keep the tool surface small. By the way, a growing number of clients now support dynamic or lazy tool discovery instead, where tools are searched for and loaded on demand rather than all upfront, but that is not yet the default everywhere, so designing for the common case still matters. I usually think of an MCP server as a service layer in front of my API, not a pass-through proxy. The API can stay granular. The MCP layer decides what the model actually needs to see.