API Design

The most natural thing to do when building an MCP server is to mirror your existing API. You have a REST endpoint for creating users, so you make a create_user tool. You have one for listing orders, so you make a list_orders tool. Fifteen endpoints become fifteen tools, each one a thin wrapper that translates JSON-RPC to HTTP and passes the response back. It works. The agent can call the tools, the tools return data, and everything looks fine in your test harness. Then you connect it to a real conversation with twenty other MCP servers loaded, and the agent starts picking the wrong tools, hallucinating parameter values, and burning half its context window on tool definitions it never uses.