Skip to content
AI Engineer Guide.

concept · concepts · intermediate · concept 8 of 16

Server design

0 of 16 complete

Why it matters

An MCP server is written once and used by hosts with different prompts, permissions and models. That changes the design constraints: the server cannot rely on a particular system prompt, cannot assume the caller is a human, and must make its capabilities legible from a description alone. Servers that mirror an internal API one-to-one produce dozens of ambiguous tools and errors that a model cannot act on.

Mental model

A server is a counter clerk serving many offices: the request must be clear without a shared history, and the receipt must say what happened. The metaphor breaks because the clerk's instructions are read by a model that may paraphrase them and will not ask a follow-up question unless the tool invites one.

How it works

An intent-shaped tool, a bound handleInteractive

Intent-shaped tools and principal-bound handles. The handle is a name the model carries forward; it grants nothing on its own.

Model

handles

Host

policy

Server

access

Store

records

Step 1/4 · intent
2 · tools/call · reconcilecall · Host → Server
{ "jsonrpc": "2.0", "id": 1,
  "method": "tools/call",
  "params": {
    "name": "invoice_reconcile",
    "arguments": { "invoiceId": "inv_221" },
    "_meta": {
      "io.modelcontextprotocol/protocolVersion":
        "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities":
        {} } } }

Step 1: intent. Hover, tap or tab to any message to inspect its payload.

Figure. One task-shaped call replaces a chain of endpoint wrappers, and the server returns an opaque handle instead of asking the model to remember a raw identifier. The handle is a name, not a capability: the same string from another principal is refused as a tool execution error with a code the model can act on.

What to notice. The failure is an unbound state handle: a handle that resolves without checking the caller lets one user continue another user's task. The rejection is isError true with code not_found, not a JSON-RPC error, because the request was well formed. Ids, subjects and the expiry are illustrative; the expired-handle path and the tool-sprawl alternative are omitted.

Text version

Sequence across Model, Host, Server and Store. Step 1, intent: an in-process Model to Host row proposing invoice_reconcile with invoiceId inv_221; it is one intent-shaped tool, not a chain of endpoint calls. Host to Server tools/call carries the same arguments and _meta naming protocolVersion 2026-07-28. Step 2, handle: an internal Server to Store row inserts handle h-77 bound to subject user_42, invoice inv_221 and an expiry. Server to Host returns resultType complete with text plus structuredContent handle h-77, state needs_review and next invoice_confirm. An in-process Host to Model row gives the observation; the model carries the handle, and the raw invoice id stays in context only as a cross-check. Step 3, confirm: Model to Host proposes invoice_confirm with handle h-77; Host to Server tools/call carries the handle; an internal Server to Store row looks up handle h-77 for subject user_42 and updates it; Server to Host returns reconciled with the invoice id. Step 4, other principal: Host to Server tools/call presents the same handle under a token for subject user_99; Server to Host returns a tool execution error, isError true, structuredContent code not_found and retryable false, with no existence leak and no stack trace.

  1. Group operations into tools by user intent, not by internal endpoint, and keep each tool's authority narrow.
  2. Write descriptions that state purpose, when to use, when not to use and what the result contains.
  3. Validate arguments against a strict schema and return a structured error with a code the model can branch on.
  4. Return stable identifiers and pagination cursors so a multi-step workflow does not depend on the model remembering raw text.
  5. Keep the server stateless where possible, and bind any stored state to the authenticated principal with an explicit handle.
  6. Expose read and write operations separately, and require the host to confirm destructive ones rather than assuming it will.

Trade-offs

ChoiceGood forCostFails when
One tool per endpointFamiliar to API developersTool sprawl and ambiguous selectionThe API has many similar endpoints
Task-shaped toolsFewer calls and clearer intentLess flexible compositionPower users need primitives
Stateless serverSimple scaling and retriesState must travel in argumentsThe workflow has many dependent steps
Rich structured outputModel can reason over fieldsLarger context costThe response is naturally a document
Trade-off mapInteractive

Good for

Familiar to API developers

Cost

Tool sprawl and ambiguous selection

Fails when

The API has many similar endpoints

  1. The API has many similar endpoints
  2. Power users need primitives
  3. The workflow has many dependent steps
  4. The response is naturally a document

Figure. Each choice with what it buys, what it costs, and the case where it loses.

What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.

Text version

Four trade-offs: One tool per endpoint is good for Familiar to API developers, costs Tool sprawl and ambiguous selection, and fails when The API has many similar endpoints. Task-shaped tools is good for Fewer calls and clearer intent, costs Less flexible composition, and fails when Power users need primitives. Stateless server is good for Simple scaling and retries, costs State must travel in arguments, and fails when The workflow has many dependent steps. Rich structured output is good for Model can reason over fields, costs Larger context cost, and fails when The response is naturally a document

Failure modes

  • Tool mirrors a REST endpoint. The model must chain five calls and loses the identifier between them. Debug: replay a real task and count the calls and the context size per step.
  • Opaque error. The server returns a stack trace and the model retries the same invalid call. Debug: classify errors in the server and check that each has a model-actionable code.
  • Unbound state handle. A task id from one user is accepted from another. Debug: call a stored handle with a different token and confirm rejection.

In production

Track calls per tool, error codes and argument validation failures. The message shapes are specified, while pagination limits, rate limits and idempotency keys are conventions you add, so publish a version and test against a host you did not write.

Common misconceptions

People think: A server should expose the whole API.

Actually: Exposing everything increases selection errors and authority; task-shaped tools are usually better.

People think: The host will validate arguments.

Actually: The host may validate, and the server is still the enforcement point for its own data.

Interview angle

A strong answer designs for an unknown host: intent-shaped tools, strict schemas, actionable errors and explicit state. It also explains why one-to-one API wrapping fails. Weak answers describe authentication and stop.

Sources