All chapters
  1. Start hereThe model proposes a call. Your code decides whether it runs
  2. Foundations · 1Functions: arguments, return values and side effects
  3. Foundations · 2Tool calling: how a model asks, and the loop that answers
  4. Foundations · 3Tool schemas: names, descriptions and argument constraints
  5. Foundations · 4Types and annotations: one source for the schema and the handler
  6. Foundations · 5Result contracts: success, error, partial result, reference
  7. Protocols · 6Discovery and selection: how the right tool gets chosen
  8. Protocols · 7MCP architecture: host, client, server, tools, resources, prompts
  9. Protocols · 8MCP on the wire: transports, lifecycle, authorization, notifications
  10. Protocols · 9Retrieval: a tool the model calls, or knowledge it is given
  11. Production · 10Implementing tools: API wrappers, database queries, files, code execution
  12. Production · 11Safety: least privilege, validation, idempotency, sandboxing
  13. Production · 12Reliability: timeouts, retries, rate limits, circuit breakers
  14. Production · 13Testing tools: contracts, stand-ins, faults and traces
  15. Reference · 14Frameworks and standards: what each one does for a tool
  16. Reference · 15Advanced: composition, pagination, streaming, binary content, observability
  17. Reference · 16The insurance lab: one submission, five tools, end to end
  18. ReferenceGlossary
  19. AboutAbout this site and its sources
Protocols · 8

MCP on the wire: transports, lifecycle, authorization, notifications

The same messages travel over a local pipe or over HTTP. How a session starts and ends, how a remote server knows who is calling, and how a server tells the client that something changed.

What you will understand
How the same MCP messages travel through a local pipe or over HTTP, and what each transport lets a server assume.
What changed
Revision 2026-07-28 made MCP stateless: no handshake, no protocol sessions, the version on every request.
What you can do
Decide what a remote server must check before it runs record_recommendation: who is calling, for which server, with which scope.

The underwriting tools of the insurance example already run as an MCP server. On a developer's laptop, the agent's host application starts mcp_server.py as a child process and talks to it through its standard input and output. Nobody logs in. The server learns its caller from an environment variable, UW_TOOLS_CALLER, which the host sets when it starts the process. It works.

Then the underwriter cockpit team asks for the same tools in their web application, on another machine. A second team wants the read tools for a broker-facing assistant. Now the server is a network service. Three questions arrive that the laptop never asked. How do the messages get there? How does the server know which program is calling, and on whose behalf? And what happens to "the conversation" when every request may land on a different server instance behind a load balancer?

This page answers those questions for the Model Context Protocol (MCP), the open protocol through which an application offers tools to a model's host. It assumes the roles from MCP architecture: the host is the application the user works in, an MCP client is the host's connector to one server, and the server is the program that offers tools. The model proposes a call; your code decides whether it runs. On a remote server, "your code" must first decide who is asking.

Before AI. The same move happened to every internal library that became a service. A Java class called in-process trusted its caller completely. The REST service that replaced it needed TLS, an OAuth token, a check that the token was meant for this service, and an answer to "where does the state live now?". MCP's transports and authorization are those answers for tools.

A transport carries messages; it does not change them#

Start with the plain idea. A transport is the way messages get from one program to another: a pipe between two processes, an HTTP connection, a socket. The messages themselves stay the same. A tools/call for get_roof_assessment with submission_id SUB-1004 is the same JSON-RPC message whether it travels through a pipe or in the body of an HTTP request.

MCP defines two standard transports, as documented on 2026-11-17 for revision 2026-07-28: stdio and Streamable HTTP. Custom transports are allowed if they keep JSON-RPC, the message patterns and the metadata on each request. Messages must be UTF-8.

One rule holds for both, and it is new in this revision: only two directions exist. The client sends requests and notifications. The server sends responses and notifications. A server never sends a request to a client. When a server needs something from the user, such as a confirmation, it returns a result that says input is required, and the client asks again with the answer. MCP architecture shows that pattern.

Diagram: Same messages, two transports · a pipe on the laptop, HTTP for the cockpit

Read left to right. The host's client sends the same JSON-RPC messages either through a pipe to a child process or as HTTP POSTs to one endpoint. What changes is how the server learns who is calling. Click a box for the rule that applies.

  1. 1 · The host
    1. MCP client: The host's connector to one server. It sends requests and notifications; it never answers a server request, because in revision 2026-07-28 servers send none.
  2. 2a · stdio
    1. Pipe: The client starts the server as a child process and writes to its stdin; replies come on stdout; logs go to stderr.
  3. 2b · Streamable HTTP
    1. One endpoint: Each message is a POST to one URL; the reply is a JSON body or an event stream for that request; headers repeat the method and tool name.
  4. 3 · Who is calling
    1. Environment: On stdio the specification says to take credentials from the environment, not from the OAuth flow.
    2. Bearer token: On HTTP the token must be issued for this server, and its scope must allow the tool.
  5. 4 · The server
    1. Execution adapter: Whatever the transport, the same adapter validates arguments and checks the caller's scope before the function runs.
stdioStreamable HTTP
Where the server runsA child process the client startsA web service at one URL, for example /mcp
How a message travelsOne JSON-RPC message per line on stdin and stdoutEach client message is its own HTTP POST
How the reply comes backA line on stdoutA JSON body, or an event stream for that one request
Who the caller isWhoever started the process; credentials from the environmentProven by a bearer token on every request
Typical use in the exampleThe developer's laptopThe cockpit and the broker assistant

stdio: a pipe between two processes#

The stdio transport is the smallest one. The client launches the server as a subprocess. The server reads JSON-RPC messages from its standard input and writes them to its standard output, one message per line. A message must not contain a newline. The server may write logs to standard error, and the client should not take that as an error. Nothing else may appear on standard output, as documented on 2026-11-17.

That last rule bites in practice. A Python tool that prints a debug line with print() corrupts the protocol stream. The example's server writes its one startup line to standard error for that reason:

print(f"[uw-tools server] case {args.case}, caller {server.caller}", file=sys.stderr)

That line is from mcp_server.py, function main, which then reads one line at a time from standard input and writes one JSON reply per line.

Who the caller is follows from the process model. The specification says stdio implementations should not use the HTTP authorization flow and should take credentials from the environment. The host that starts the process decides what the process may do. In the example the host sets UW_TOOLS_CALLER; started as assessment-agent, the same server refuses record_recommendation with not_authorized (case UW-T03), because that caller holds only the scope uw.read.

Shutdown is also the host's job. The client closes the server's standard input, waits, and then terminates the process if it has not exited. If the server dies, the client should restart it; requests that were in flight are lost.

In a coding agent. Most local coding-agent tools that speak MCP run this way: the agent's harness starts a server for the repository, passes it a working directory and credentials through the environment, and reads its stdout. The harness, not the model, holds the power to start and stop it. See harness.sammuthu.com for the runtime around such tools.

Streamable HTTP: one endpoint, one POST per message#

For the cockpit, the server becomes a web service. Streamable HTTP, as documented on 2026-11-17, works like this. The server offers a single endpoint that accepts POST. Every client message is its own POST. The client must accept both application/json and text/event-stream. The server answers a request either with one JSON object or with an event stream that belongs to that one request: on it the server may first send notifications about the request, such as progress, and then the final response. A notification the server accepts gets 202 Accepted with no body.

Every POST also carries headers that repeat what is in the body, so that proxies and gateways can route and filter without parsing JSON. MCP-Protocol-Version must match the version in the request's _meta. Mcp-Method names the method, and Mcp-Name names the tool or resource for tools/call, resources/read and prompts/get. A mismatch between header and body is rejected with 400 and the MCP error HeaderMismatch, code -32020.

Plain English. The body says "call record_recommendation". The header says the same thing on the outside of the envelope. A gateway that only allows read tools for the broker assistant can block the request by looking at Mcp-Name, and the server refuses any request where the outside and the inside disagree.

The transport also protects a local HTTP server from web pages. The specification says servers must validate the Origin header on every connection and answer 403 to an invalid one, and that local servers should listen on 127.0.0.1, not on all interfaces. Without this, a page in the developer's browser could reach a tool server on their laptop. This attack is known as DNS rebinding.

The example's server speaks stdio only. Everything in this section is described from the specification and was not run here.

No handshake, no protocol session#

Here the current revision differs from most tutorials. Until revision 2025-11-25, an MCP connection started with a handshake. The client sent initialize with its protocol version and capabilities, the server answered with its own, and the client confirmed with notifications/initialized. Over HTTP the server could then hand out an Mcp-Session-Id header, and later requests on that session relied on what the handshake had agreed.

Revision 2026-07-28 removed both, as documented on 2026-11-17. MCP now calls itself stateless. Every request carries its protocol version and the client's capabilities in _meta. A server must not rely on an earlier request on the same connection for the version, the capabilities or the client's identity. A stdio process is not a session either. The server offers a mandatory method server/discover that a client may call first to learn the supported versions and capabilities.

The reason is the cockpit's load balancer. With sessions, request 2 had to reach the server instance that saw request 1, or the agreed state was missing. Without sessions, any instance can answer any request, because everything it needs is in the request. A Spring engineer knows the same trade from moving server-side HTTP sessions out of a cluster: stateless services scale out and fail over without coordination; state that must survive becomes an explicit id stored somewhere.

Here are the example's server answers, captured by mcp_client.py in a scratch copy. A successful run proves three rules of the stateless revision: discovery advertises one version, a request without the required _meta is refused, and a legacy initialize is refused with the supported version named.

cd examples/uw-tools
/opt/homebrew/bin/python3 mcp_client.py
2  server → client  server/discover   result: supportedVersions ["2026-07-28"], capabilities {tools, resources, prompts}, ttlMs 3600000, cacheScope "public"
20 server → client  tools/list (version 2024-01-01)   error -32022 "Unsupported protocol version"  data {supported: ["2026-07-28"], requested: "2024-01-01"}
22 server → client  tools/list (no _meta)   error -32602 "Invalid params: _meta must carry io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities"
24 server → client  initialize (2025-11-25)   error -32601 "Method not found: this server speaks MCP 2026-07-28 only (no initialize handshake); send server/discover with _meta instead"

(Four of the 24 recorded messages, shortened to one line each; the numbers are the message numbers of the transcript.) This is a teaching subset written from the specification, not the official SDK, and it is not conformance tested.

The lab below steps through the whole session. It starts at the first error. The table after it gives the same messages for a reader without JavaScript.

#SenderMethodWhat it shows
1, 2client, serverserver/discoverVersions, capabilities, server info; every request carries _meta with the protocol version
3, 4client, servertools/listThe five definitions with inputSchema and annotations
5, 6client, servertools/callA call the model proposed; the result has content, structuredContent (the envelope), isError false
7, 8client, servertools/callWrong type (UW-T01): a tool execution error, isError true
9, 10client, servertools/callUnknown tool (UW-T02): JSON-RPC error -32602
11 to 16client, serverresources/list, resources/read, prompts/listResources are application-controlled; prompts are user-controlled
17, 18client, servertools/deleteUnknown method: -32601
19 to 22client, servertools/listUnsupported version: -32022; missing _meta: -32602
23, 24client, serverinitializeA legacy 2025-11-25 client: -32601, the server names the version it supports
Common confusion. "Stateless protocol" does not mean "stateless tools". record_recommendation still writes a row, and the idempotency key still keeps a retried write to one row. The protocol keeps no conversation state between requests; your tools keep whatever business state they need, under explicit ids.

Notifications: telling the client something changed#

A notification is a JSON-RPC message with no id. The receiver must not answer it, so the sender learns nothing about whether it arrived. That is why notifications carry news, never commands that need confirmation.

MCP uses two kinds, as documented on 2026-11-17. Request-scoped notifications belong to one request: notifications/progress while a slow tool runs (see Advanced), or a cancellation. On stdio the client cancels with notifications/cancelled and the request id. On HTTP, closing the response stream is the cancellation signal.

Change notifications tell a client that a list changed, for example that the server now offers a sixth tool. In revision 2026-07-28 a client opts in with a long-lived request, subscriptions/listen, naming the kinds it wants, such as toolsListChanged. The server acknowledges and then sends matching notifications on that request's stream, each tagged with the subscription id. This replaced both the HTTP GET stream and resources/subscribe of the earlier revision.

For tools this matters in one practical way. A host that caches the catalog should refresh it when notifications/tools/list_changed arrives, or when the ttlMs the server gave with the list runs out. A tool that disappeared, or whose schema changed, otherwise reaches the model from a stale cache.

Authorization: who is calling, for which server, with which scope#

Back to the cockpit. On HTTP, an environment variable no longer says who the caller is. Anyone who can reach the URL can send a POST. The server must learn three things before it runs record_recommendation: which program is calling, on behalf of which person, and whether that combination may write.

MCP's authorization specification answers with OAuth. OAuth is the standard way for a program to obtain a token that lets it call a service on someone's behalf, without ever seeing that person's password. A tiny example: the cockpit sends the underwriter to a sign-in page of the insurer's identity service; the identity service gives the cockpit a token; the cockpit sends that token with each request to the tool server.

As documented on 2026-11-17, authorization is optional in MCP, HTTP implementations should follow it, and stdio implementations should not. The roles are those of OAuth 2.1: the MCP server is a resource server, the MCP client is an OAuth client, and an authorization server issues tokens. The rules that matter most for tools are these:

Rule (as documented)What it prevents in the example
The server publishes Protected Resource Metadata (RFC 9728) that names its authorization serversThe cockpit discovers where to get a token without configuration by hand
The client sends the resource parameter (RFC 8707) with the server's canonical URI, and the server checks the token was issued for itselfA token meant for another service cannot be replayed against the tool server
The token goes in Authorization: Bearer on every request, never in the URLTokens do not leak into logs and browser history
Insufficient scope gets 403 with error="insufficient_scope" and the scope neededThe broker assistant, holding only read scope, is refused record_recommendation and told why
PKCE is mandatory for clientsA stolen authorization code cannot be exchanged by someone else
The server must not pass the client's token on to other servicesThe tool server calls the roof-data provider with its own credentials, so the audit trail stays honest

The scope rule connects directly to the example. On this site, record_recommendation needs the scope uw.recommend, and the read tools need uw.read. Over stdio, the example maps the caller to scopes in tools.py. Over HTTP, those scopes would come from the token, and the server's adapter would check them in the same place it checks them today. Safety explains why the write tool needs more than the reads.

Production pitfall. A valid token proves who is calling, not what they may do with this tool. Check the scope inside the adapter for every call, not only at the HTTP layer. A gateway rule on Mcp-Name is a useful second line, never the only one.
What this is not. Agent-to-agent messages, where one agent hands a task to another and waits for its result, are a different protocol and belong to https://a2a.sammuthu.com. Enforceable checks around the agent beyond authorization belong to https://guardrails.sammuthu.com.
Serving modern and legacy clients at onceHow a client detects the revision, and why the fallback must not key on one error code

Real fleets mix revisions. The documentation names three kinds of implementation: modern (revision 2026-07-28 and later), legacy (2025-11-25 and earlier, with the handshake), and dual-era, which serves both. A legacy-only client cannot talk to a modern-only server.

On stdio, a dual-era client probes with server/discover. A discovery result, or a recognized modern error, means the server is modern. Any other error, or a timeout, means legacy, and the client falls back to initialize. The specification says the fallback must not depend on one specific error code. The example's server answers a legacy initialize with -32601 and names the supported version in data, which a dual-era client can read; a client that waited for exactly -32601 would break on a server that answers differently.

Over HTTP, a dual-era client tries a modern request first, and on a 400 inspects the body. A server may also treat a request without the MCP-Protocol-Version header as the old 2025-03-26 revision if it still supports such clients; otherwise it must reject it.

The operational advice that follows: pin and log the revision each client used, per request. Without sessions, there is no connection-level record of it. Revision drift between a host and a server then shows up in the logs instead of as a mysterious "method not found".

Where state goes when the protocol forgets itExplicit handles, binding them to the user, and the idempotency key as a handle

Removing protocol sessions does not remove the need for state. A paged search needs to remember where page 2 starts. A multi-step workflow needs to remember step 1. The specification's answer, as documented on 2026-11-17, is explicit handles: a server that needs cross-call state mints a handle and the client passes it as an ordinary argument.

The cursor cur-5 of search_guidance in case UW-T07 is such a handle, and so is the idempotency key SUB-1004:run-7f3a:recommendation, although the application chooses that one.

Handles bring the security problem that sessions had. The security best-practices page read on 2026-11-17 replaced its "Session Hijacking" section with "State Handle Hijacking": a server must not treat possession of a handle as authentication, should make handles random and unguessable, and should bind them to the authenticated user, for example by keying state as user id plus handle. Apply that to the example: a recommendation stored under an idempotency key must also record the caller, and a replay from a different caller with the same key must be refused as a conflict, never answered with the stored result.

Storage is the other half. A stateless protocol behind a load balancer needs state in a shared store, not in process memory. The example's rows live in memory because it runs one process. Durable state and checkpoints are the subject of https://memory.sammuthu.com.

The confused deputy and the proxy serverWhy an MCP server that fronts another API must ask for consent itself

A confused deputy is a program with more authority than its caller, tricked into using that authority on the caller's behalf. MCP servers are often deputies: the uw-tools server holds credentials for the roof-data provider that the cockpit does not hold.

The security best-practices page read on 2026-11-17 describes a specific case. An MCP server acts as a proxy to a third-party API, uses one static client id at that third party's authorization server, lets its own clients register dynamically, and relies on the third party's consent cookie. An attacker can then get an authorization code sent to their own redirect address. The mitigations named are per-client consent at the MCP server before forwarding, exact matching of redirect addresses, and single-use state values.

Two rules from the same page close the general case. The server must not accept tokens that were not issued for it, and it must not pass a client's token through to an upstream service. Both keep each hop accountable: the provider's logs show the tool server, the tool server's logs show the cockpit and the underwriter, and no token travels further than its audience.

The registration path also changed in this revision. Dynamic Client Registration is deprecated in favor of Client ID Metadata Documents, where the client id is an HTTPS address that points to a document describing the client. Registered credentials must be kept per authorization server and never reused with another one. Check which path your identity provider supports before you design the cockpit's sign-in.

Checklist#

CheckWhy
A stdio server writes only protocol messages to stdout and logs to stderrOne stray print corrupts the stream
A stdio server takes its caller and credentials from the environment its host setsThere is no token on stdio; the host is the authority
An HTTP server validates Origin, binds locally to 127.0.0.1, and authenticates every requestWeb pages and strangers cannot reach the tools
The server checks the token's audience is itself, and the scope inside the adapter for every callA valid token for another service, or a read-only token, cannot write
No state depends on an earlier request on the same connection; handles are random and bound to the userAny instance can serve any request, and a stolen handle is not a login
The protocol revision each request used is loggedRevision drift is visible without sessions
Catalog caches honor ttlMs and list-changed notificationsThe model never sees a tool that no longer exists

In one breath#

MCP messages travel over stdio, one line per message between a host and its child process, or over Streamable HTTP, one POST per message to one endpoint. Revision 2026-07-28 made the protocol stateless: every request carries its version and capabilities, there is no handshake and no session, and state lives under explicit handles. On HTTP the server must prove who is calling with OAuth, check that the token was issued for itself, and check the scope for every tool call, because a remote write is only as safe as the check in front of it.

You can now run the example's tools locally or plan them as a remote service, and say what each side must verify. One question has been waiting since the first page: searching the guidance is a tool here, but it could also be knowledge the application attaches. Who should choose the query, and how is retrieved text kept from giving orders? That is Retrieval.