An MCP server is an API with opinions
Anyone can wrap an existing API in the Model Context Protocol in an afternoon. Getting a model to use that server correctly, every time, is a separate piece of work most teams skip.
The short version
5 things that decide this
- 01An MCP server is not a thin wrapper around an API. It is a design surface: the model only knows what the tool names, descriptions and results tell it.
- 02A tool named after a database table forces the model to guess what it does. A tool named after the task the model is trying to complete does not.
- 03A tool's description is the model's only contract. If it does not state the required arguments, their format and what a failure looks like, the model will call the tool wrong and blame itself.
- 04Results sized for a person, not a context window, push everything else out of the model's working memory. A tool should return what the task needs, not the full record.
- 05Errors need to tell the model what to do next. 'Error 422' sends it in circles. 'Missing required field: customer_id' lets it retry correctly.
Most MCP servers are a REST API with new labels
The fastest way to build an MCP server is to wrap an existing API, one tool per endpoint. GET /customers/:id becomes get_customer. POST /invoices becomes create_invoice. It works. The server starts and the tools appear in the model's list.
It also carries over every problem the API had for a human developer. But the model cannot read the full documentation, ask a colleague, or set a breakpoint. It sees only what the tool list shows: a name, a description, a schema. Thin ones leave it as confused as a new engineer on day one, with nobody to ask.
Four things the model actually reads
A model choosing between tools has no access to your codebase, your database schema or your internal naming conventions. It has the tool list. Everything it decides comes from four places, and each one is a design decision, not a formality.
- 01Tool names should describe intent, not implementation. find_overdue_invoices tells the model when to reach for it. query_invoices_table does not, because the model has to infer what 'query' means here.
- 02Descriptions carry the contract: required arguments, their exact format, what a successful result looks like, and what happens on failure. A one-line description is a tool the model will misuse.
- 03Results should be sized for the task, not for a person reading a report. Returning a full customer record with forty fields when the model asked for an email address pushes everything else out of its context window.
- 04Errors should name the fix. A validation failure that says which field was wrong and what format it expects lets the model correct itself in the next call, instead of retrying the same broken request.
Where a thin wrapper is the right call
None of this means every endpoint needs its own bespoke tool. A single internal agent, built and maintained by the same team that owns the API, can often work fine against a direct mirror of it. The team already knows the API's quirks and can fix a bad call in the prompt or the agent's own code.
The design work earns its cost once a server has to work for models it was not tuned against. It also earns its cost once the person debugging a wrong call is not the person who wrote the API. That describes most production servers. The point of publishing one is usually so other teams can call it without asking first.
Questions this raises
01What separates a well-designed MCP server from one that merely works?
A well-designed server names tools by intent and writes descriptions that specify arguments and failure modes. Results are sized for the task, not the full record, and errors say what to fix. A server that merely works returns correct data when called correctly. A well-designed one helps the model call it correctly in the first place.
02Should every API endpoint become its own MCP tool?
Not always. Mirroring endpoints one-to-one is fine for a single internal agent maintained by the API's own team. It becomes a liability once other agents or teams call the server without the context to work around a confusing tool.
03How much detail belongs in a tool's description?
Enough that the model never has to guess. State the required arguments and their exact format, what a successful call returns, and what a failure looks like. A one-sentence description is usually too little for anything beyond the simplest tool.
