MCP Server

What it is

The providing half of a Model Context Protocol connection: a process that wraps a system you operate and advertises it as a set of callable tools, readable resources, and reusable prompt templates, then serves requests against them. Designing one is mostly an authoring problem — deciding what to expose, at what granularity, under what names, described in prose a model reads correctly — and only secondarily a transport problem.

Why it matters

A server is a public contract with an audience that cannot ask clarifying questions. The descriptions you write are the entire specification as far as the calling model is concerned, and they are evaluated on every turn by a reader that will not consult your documentation. Granularity is equally consequential: a surface that mirrors an internal API turns a single user intention into a long chain of calls, each one an opportunity to pick the wrong argument, while a surface built around tasks does the composition once, in code you can test.

Exposing a surface is not publishing a catalogue

What a server advertises is live, scoped to the connection, and shaped by who authenticated: two callers can legitimately be offered different things by the same process. A catalogue is the organisation's durable record of which tools exist, who owns them, and which are retired, and it stays accurate when the server is down. A server's advertised list is evidence about right now; it is not a governance artefact and should not be used as one.

Key decisions

• Granularity. One tool per backing endpoint keeps the implementation thin and pushes orchestration onto the model; task-shaped tools that compose several calls are harder to write, far easier for a model to use correctly, and need their own partial-failure story.
• Which of the protocol's offering types a thing should be. Material the caller reads is usually a resource; an action with an effect is a tool; a reusable interaction shape is a prompt template. Exposing read-only data as a tool is the common mistake.
• Whether sessions carry state. Stateless request handling scales behind any number of replicas; session-bound state means sticky routing, an eviction policy, and a defined behaviour when a client reconnects after an outage.
• How failures are reported. A failure the model can reason about and retry differently belongs in a tool result marked as an error; a failure in the protocol exchange itself belongs in a protocol error. Putting a business failure in the second hides it from the model.
• Whose identity reaches the backing system: a single service account the server holds, or the authenticated caller's own identity carried through. The first is simpler and makes per-user authorisation and audit impossible.
• What a large result does. A tool that can return megabytes needs an explicit ceiling, a truncation signal, and a way to fetch the remainder, decided by you rather than by whichever client connects.
• How the advertised surface is versioned, and what a connected client experiences when a tool's arguments change underneath it.

Failure modes

• The surface mirrors forty backing endpoints one-for-one, so a routine request becomes a nine-call sequence and fails somewhere in the middle with half the work done.
• Descriptions are generated from internal code comments, so the model is told about implementation details and nothing about when the tool is the right choice.
• A business error is returned as a protocol-level error, the client treats it as a transport problem, and the model never learns that the record it asked for simply does not exist.
• The server keeps per-connection state in process memory, works perfectly on one replica, and breaks the moment a second is added behind a load balancer.
• A single tool returns an unbounded listing, and the client's context is consumed by rows nobody will read.
• Every call runs under one highly privileged credential, so the backing system's own access controls see one caller and can neither restrict nor attribute anything.
• An argument is renamed in a release, connected clients hold the old declaration, and calls fail with validation errors that give no hint that the contract moved.
• A long-running operation holds the request open with no progress signal, and the client's deadline fires while the work continues to completion unobserved.

Related capabilities

• MCP Client — the consumer whose constraints shape what is worth exposing
• MCP Gateway — aggregates servers like this one behind a single endpoint
• MCP Authentication — establishes which caller a request is served for
• Tool Registry — the durable record an advertised surface is not
• Tool Result Normalization — the shaping decisions a result needs

Applies: Production readiness · Design questions