We're Building MCP Servers Wrong

When most developers build their first MCP server, they do something predictable: they take their REST API and wrap each endpoint as an MCP tool. GET /users becomes a get_users tool. POST /orders becomes a create_order tool. The mapping is 1:1, mechanical, and wrong.

It's wrong because REST APIs are designed for developers who read documentation, understand data models, and can chain multiple calls together in their head. LLMs don't work that way. They work with tool descriptions, not docs. They reason about individual tool calls, not API workflows.

When you blindly map REST to MCP, you force the LLM to reconstruct the mental model that your API docs would have given a human developer. Sometimes it succeeds. Often it doesn't. And when it doesn't, you blame the LLM instead of the tool design.

The fundamental shift in thinking is this: REST endpoints model resources. MCP tools should model tasks.

A REST API has GET /users/{id}, GET /users/{id}/orders, GET /orders/{id}/items. Three endpoints, three calls, three responses that the consumer stitches together.

An MCP server should have a get_user_order_summary tool that returns everything the LLM needs in one call. The LLM asked "what did this user order?" — give it the answer, not three puzzle pieces.

This feels wrong to API purists. It violates normalization. It duplicates data. It creates "fat" responses. But the consumer isn't a developer writing clean code — it's an LLM that performs better with fewer, more complete tool calls. Optimize for the consumer, not for architectural elegance.

In a REST API, the endpoint path and HTTP method carry semantic information. GET /users is obvious. POST /payments/refund is self-explanatory. Developers can often guess what an endpoint does before reading the docs.

LLMs don't parse URL patterns. They read tool descriptions. Your tool description is the only documentation that matters. If it's vague, the LLM will use the tool wrong. If it's misleading, the LLM will use the tool at the wrong time. If it's incomplete, the LLM will pass wrong parameters.

Write descriptions like you're explaining the tool to a very literal colleague who has no context about your system. Say exactly what the tool does, what it returns, when it should be used, and when it should NOT be used. The negative case matters as much as the positive case — "Use this to search documents. Do NOT use this for searching users or permissions."

Most MCP servers have descriptions that would get a D in a technical writing class. This is the single highest-leverage improvement you can make.

Here's a pattern I see constantly: an MCP server with search_documents, find_documents, and query_documents. Three tools that do almost the same thing with slightly different parameters.

To a human developer, the differences are obvious — maybe one searches by content, another by metadata, and the third by date range. To an LLM, these are three tools with similar descriptions, and it has to guess which one to use. It guesses wrong about 40% of the time.

Tool overlap is the number one source of MCP reliability problems. Every time the LLM has to choose between similar tools, there's a chance it chooses wrong. The solution is ruthless deduplication. If two tools can be merged without losing important functionality, merge them. Add parameters instead of adding tools.

Fewer, more capable tools always beat many specialized tools. A Swiss Army knife is useful. A drawer full of slightly different corkscrews is confusing.

The meta-lesson is simple: MCP tools have a different consumer than REST APIs, and different consumers need different designs.

Test your tools with actual LLMs. Not just "does the tool execute correctly" — but "does the LLM choose the right tool, pass the right parameters, and interpret the response correctly?" This is a different kind of testing, and most teams don't do it.

Monitor how LLMs actually use your tools in production. You'll find surprising patterns — tools used in ways you didn't expect, tools ignored because their descriptions are ambiguous, tools called repeatedly because the LLM doesn't realize the first call already returned what it needed.

The best MCP servers aren't the ones with the most tools or the cleanest architecture. They're the ones where the LLM gets the right answer on the first try, every time. That's the only metric that matters.