The demo always works. Someone wraps a REST API, exposes all 38 endpoints as tools, connects it to Claude or Cursor and asks for one invoice. The invoice comes back. A week later the same agent is calling list_invoices when it meant get_invoice. It pulls 40 KB of JSON, roughly 10,000 tokens, to answer whether one invoice is paid. Then it retries a 422 four times, because all it can see is "Unprocessable Entity".
None of that is a protocol problem. The SDKs give you transports, JSON Schema and the initialize handshake in an afternoon. The user you're really designing for is a model that picks between tools it knows only by a name, a description and a schema, and it reads all of them on every turn. Every practice below follows from treating that model as the user.
Design tools around jobs, not endpoints
The first failure is usually a one-to-one mapping from routes to tools. get_customer, list_orders, get_order and get_shipment make a sensible resource model for code. Ask a model "where is Sara's last order?" and it now has to plan four calls, carry a customer ID into the second and an order ID into the third, and get every hop right. If each call is right 95% of the time, the four-call chain succeeds about 81% of the time.
Expose the job instead: find_order_status takes an email or an order number and returns the status, carrier and expected delivery date. Your server makes the four API calls itself, in deterministic code that never invents an ID. The tool definitions shrink too. At roughly 200 tokens each, 38 tools add about 7,600 tokens of schema to every request before the user has typed a word. Deciding which jobs deserve a tool is the real design work, and it takes most of the hours we spend building production MCP servers.
The description is the interface
The model never sees your README. When it decides whether to call a tool, it has the description and nothing else. So the description has to say when to use the tool, when not to, and what comes back. "Gets order data" gives the model nothing to decide with. "Look up the current status of one order by order number or customer email. Use for delivery and tracking questions. Do not use for refunds; call issue_refund" gives it a decision rule.
Schemas matter just as much. Use enums wherever the values are known, so status: "shipped" can't arrive as "Shipped" or "in transit". Mark only the fields that are truly needed as required. Put the format in the schema, with "format": "date" and an example, instead of hoping the model picks ISO 8601 over 21/10/2026. When two descriptions overlap, like search_customers and find_customer, choosing between them becomes a coin flip. Merge the tools or write the boundary into both descriptions. A two-line description edit often fixes more misfires than a code change does.
Return less, and make it pageable
Every byte a tool returns lands in the context window. A raw API payload full of nested _links, audit timestamps and internal UUIDs costs tokens and hides the one field the model needs. Return the fields a person would read, with plain-word labels, and include IDs only where a follow-up call will use them. Our MCP token cost benchmark measures this, and response shape is one of the cheapest wins in it.
Any tool that returns a list needs a limit, a cursor and a default page size of around 20. End the result with a line like "Showing 20 of 312. Pass cursor=abc to continue." Without paging, one broad search_tickets call can return thousands of rows and crowd out the system prompt. The agent then ignores instructions it was following a turn earlier. A response_format parameter with concise and detailed values also helps: the model skims IDs and titles first, then fetches full records only for the two it cares about.
Write errors the model can act on
When a tool fails, return a normal tool result with isError: true, not a JSON-RPC error. The model reads an error result and changes course. A protocol error often reaches it as a generic failure, or doesn't reach it at all. The message should name the problem and the next step. "No order found for sara@example.com. Try the order number, which starts with ORD-" turns a dead end into a second call that works.
Validate inputs at the boundary and name the field. "delivery_date must be YYYY-MM-DD; got 21/10/2026" gets fixed on the next turn, while a bare 400 gets retried unchanged. Make writes idempotent with a client-supplied key, because models retry after timeouts and a non-idempotent create_invoice will bill the customer twice. Give destructive actions their own tools, such as delete_customer instead of a mode flag on update_customer, and mark them with destructiveHint so clients can ask for confirmation first. Auth scoping and prompt injection through tool output need a separate pass, and our MCP server security checklist covers that side.
Test with a model in the loop
Unit tests prove a tool returns the right data when it's called correctly. They tell you nothing about whether a model will call it correctly. Write 30 to 50 realistic requests, phrased the way users actually type them, and run them through a real client. Check which tools were called, with which arguments, and whether the final answer was right. Rerun the full set after every description or schema change, because renaming one parameter from q to query can change how often the model fills it in.
In production, log every call with its arguments, latency, result size in tokens and error flag. Within a week the patterns are obvious: a tool that never gets called, a parameter that fails validation on most calls, a search that's almost always followed by a narrower second search. Each of these is a design bug on your side, not a model bug. Our notes on how to test LLM code show how to score these runs without writing assertions that fail at random.
Questions, answered.
What are the most important MCP server development best practices?
Build a small set of tools around user jobs instead of API endpoints, and write descriptions that tell the model when to use each one and when not to. Keep responses short and paged, and return errors as isError results that say what to try next.
How many tools should an MCP server expose?
As few as it takes to cover the real jobs. Every definition, usually a couple of hundred tokens, is sent with every request, and overlapping tools make the model choose at random. If two tools keep getting confused, merge them or write the boundary into both descriptions.
Should I map my REST API directly to MCP tools?
Usually not. A one-to-one mapping makes the model chain several calls and pass IDs between them, and every hop adds tokens and another chance to fail. Wrap common multi-step flows in one outcome-shaped tool and let your server code handle the orchestration.
How should an MCP tool handle errors?
Return a normal tool result with isError set to true and a plain message that names the failing field or condition and the next step. JSON-RPC errors and raw stack traces give the model nothing it can act on.
How do you test an MCP server?
Unit test the tool logic, then run 30 to 50 realistic requests through a real model client. Check which tools were called, with what arguments, and whether the answer was correct. Rerun the set whenever a description or schema changes.