MCP Architecture

MCP separates three roles. The host is the application the user talks to — an IDE, a chat application or an agent runtime such as Claude Code, VS Code with Copilot or a custom LangChain agent (see Connecting Hosts). The host owns the conversation with the model, decides which tools the model may see, shows confirmation prompts, and enforces security boundaries. The client is the protocol component inside the host that speaks to exactly one server; a host with three configured servers runs three clients. The server is the program that exposes tools, resources and prompts — a local subprocess or a remote HTTP service.

The design goals in the specification’s architecture page follow from this split: servers should be easy to build and focused on one capability, they should compose, and a server must not be able to read the whole conversation or "see into" another server. The host keeps the full conversation and mediates every cross-server interaction, so a server only ever receives the arguments of the request addressed to it. That is why tool descriptions returned by a server are treated as untrusted input by careful hosts (see MCP Security).

Two roles are easy to confuse with the above. The model never speaks MCP: the host translates tool definitions into the model provider’s function-calling format (see Structured Output & Tool Calling) and turns the model’s tool calls back into tools/call requests. And an agent framework such as LangChain is usually the host: it embeds one or more MCP clients (see Building MCP Clients) and feeds the tools into its agent loop (see Agent Loop & Architectures).

Every MCP message is a JSON-RPC 2.0 object. A request carries jsonrpc, id, method and params; the receiver answers with a response carrying the same id and either result or error. A notification has no id and gets no reply. The transport decides how messages travel (see Transports); the message shapes are the same everywhere.

Failures come in two layers. A protocol-level failure is a JSON-RPC error object with a numeric code: the standard codes (-32700 parse error, -32600 invalid request, -32601 method not found, -32602 invalid params, -32603 internal error) plus, in 2026-07-28, a range the specification reserves for itself, -32020 to -32099, of which three codes are allocated so far:

The second layer is the tool result: a tool that ran and failed reports isError: true inside a normal result, which is covered on Tools, Resources, Prompts & Elicitation.

Before 2026-07-28 every connection began with an initialize request in which client and server exchanged protocol versions, capabilities and identities, followed by an initialized notification. The server then held that agreed state — and, on HTTP, an Mcp-Session-Id — for the life of the connection. The 2026-07-28 revision removes the handshake, protocol-level sessions and the session header. Nothing about a request depends on an earlier request: each one is self-describing.

The mechanism is the _meta object that already existed on every request. Three keys in the reserved io.modelcontextprotocol/ namespace now carry what the handshake used to establish:

A request that omits a required key is malformed: the server answers -32602, and on HTTP with status 400. The server identifies itself the same way in the other direction, in every result’s _meta under io.modelcontextprotocol/serverInfo. Both info objects are self-reported and unverified, so the specification tells implementations not to base behaviour or security decisions on them.

A version mismatch is handled per request rather than negotiated once. If the server does not implement the version a request declares, it returns UnsupportedProtocolVersion (-32022) with the versions it does support, and the client retries with one of them:

That response is real output from the Python docs-assistant server when it was sent a request declaring 2099-01-01. The practical effect of statelessness is that any server instance can answer any request. There is no session to replicate or pin, which is what allows plain round-robin load balancing (see Transports and Deploying Remote Servers). Anything a server needs to remember between two requests — the classic example is the state of a multi-step elicitation — travels inside the messages themselves (requestState, covered on Tools, Resources, Prompts & Elicitation).

server/discover is how a client asks a server, before anything else, which protocol versions it supports, which capabilities it declares and who it is. Servers must implement it. Clients may call it but do not have to: a client can send any request inline and react to UnsupportedProtocolVersion if its preferred version is not supported. Discovery earns its keep in two situations. A client that wants to show what a server offers can do so from one response instead of probing tools/list, prompts/list and resources/list separately, and a client on stdio that supports both eras uses it as the probe that decides between the modern and the legacy protocol, because stdio has no HTTP status code to trigger a fallback.

The result carries supportedVersions, capabilities, optional natural-language instructions for the model, and the serverInfo in _meta. Like the list results it is cacheable, so it also carries ttlMs and cacheScope (see Tools, Resources, Prompts & Elicitation). Capabilities are declared per feature; the docs-assistant server advertises tools, resources and prompts, each with listChanged, and resources with subscribe.

Everything beyond the core is negotiated as an extension. Both sides advertise the extensions they support in the extensions field of their capabilities, a map from an extension identifier to that extension’s settings object. An identifier follows the _meta naming rules — a mandatory vendor prefix, a slash, a name — so official extensions live under io.modelcontextprotocol/ and third parties use a reversed domain they own, such as com.example/…​. If only one party supports an extension, the other side reverts to core behaviour or rejects the request; an empty settings object means "supported, no options". Extensions are optional, additive, and versioned independently of the core.

Three official extensions matter for the rest of this sub-section:

Because extension settings ride in clientCapabilities on every request, an extension is negotiated per request like everything else. Authorization extensions (client credentials, enterprise-managed authorization) follow the same mechanism and are mentioned on Authorization.

The keys traceparent, tracestate and baggage are reserved in _meta for OpenTelemetry context propagation, with values in the W3C Trace Context and Baggage formats. A host that already has an active span puts its traceparent into the request’s _meta, and a server that instruments its handlers continues the same trace:

The value shown is the specification’s own example. Since there is no connection identity to correlate on any more, this is the supported way to follow one user action from the host through the MCP server into the systems behind it. See Testing & Debugging for how it fits with logs, and the OpenTelemetry semantic conventions for MCP for span names and attributes.

This subsection is history, because most books, blog posts and older SDK versions describe the previous design and you will meet it in real deployments. Protocol versions 2025-11-25 and earlier — the specification calls them the legacy era — worked like this. The transport was first the HTTP+SSE pair of 2024-11-05, then Streamable HTTP from 2025-03-26. A client opened a connection and sent initialize; the server replied with its version, capabilities and info; the client confirmed with a notification; and only then could requests flow. On HTTP the server could mint an Mcp-Session-Id that the client had to echo, a client could open a long-lived GET stream to receive server-initiated messages, servers could send their own JSON-RPC requests (sampling, elicitation, roots) down a stream, and streams could be resumed with Last-Event-ID. Every one of those mechanisms needs state that lives in one server process, which is why deployments needed sticky routing or a shared session store.

Revision 2026-07-28 — the modern era — replaced them piece by piece:

The specification defines dual-era implementations that speak both, and gives a fallback rule: a client tries a modern request first and, if the server answers with something that is not a recognised modern JSON-RPC error, falls back to initialize. The official SDKs implement that rule for you. The Python Client defaults to mode="auto", which probes server/discover and falls back to the handshake on legacy servers. The TypeScript client implements the same rule during connect(), but only when asked: its versionNegotiation option defaults to 'legacy' (the plain initialize sequence), so pass { mode: 'auto' } to opt in. The Java SDK 2.0.x has not adopted the modern era: it always performs initialize, and a Spring AI 2.0.1 server answers a 2026-07-28 client’s initialize with 2025-11-25. Servers built with it are still reachable from current hosts through the fallback, but they cannot offer multi-round-trip elicitation (see Spring Boot MCP Servers).

Each request below is an independent HTTP POST to the same endpoint; nothing links them but the client’s own logic. The messages are trimmed from a real session against the Python docs-assistant server started with python server.py streamable-http (the complete transcript, with headers, is on Transports). Every request also carries the _meta block shown in the first one; later requests abbreviate it as "_meta": { …​ }.

The title keywords the Python SDK generates and the $defs block of the full outputSchema are omitted here; the whole document is on Tools, Resources, Prompts & Elicitation.

resultType: "complete" is on every final result; the alternative, input_required, is what a server returns when it needs the client to answer something first. The text block duplicates structuredContent for clients that only read content.