Skip to content

protocol-versions.md

Latest commit

 

History

History
214 lines (169 loc) · 11.6 KB

protocol-versions.md

File metadata and controls

214 lines (169 loc) · 11.6 KB
Raw

Protocol versions

MCP has two eras. Everything up to 2025-11-25 opens with an initialize handshake and keeps the negotiated revision on a session. Protocol revision 2026-07-28 removed both: everything a server needs to answer a request travels in that request, so any process can answer any request and none of them need to share state.

The SDK serves both, and a server built the ordinary way answers either. This page is the map; the mechanics live with the task they belong to.

The two eras

Handshake era (2025-11-25 and earlier) Modern era (2026-07-28)
Opening initialize / notifications/initialized none
Version negotiated once, kept on the session declared on every request
Capabilities exchanged once declared on every request
Discovery initialize result server/discover
Sessions Mcp-Session-Id removed
Server → client requests sent as JSON-RPC requests returned in the result (MRTR)
Change notifications HTTP GET stream, resources/subscribe subscriptions/listen
Dispatcher Protocol StatelessProtocol
HTTP entry StreamableHttpTransport — the same one, for both
stdio entry StdioTransport — the same one, settled by the client's first request

ProtocolVersion::isModern() tells the two apart, and Mcp\Schema\Enum\ProtocolVersion::FIRST_MODERN_VERSION is where the boundary sits.

Negotiating in the handshake era

Revisions up to 2025-11-25 agree on one during initialize. The client names the revision it wants to speak, and the server answers with the revision the connection will actually use. Both sides disconnect if they cannot agree. This follows the protocol version negotiation section of the specification. The modern era negotiates nothing — each request names its own revision.

The SDK's known revisions live in Mcp\Schema\Enum\ProtocolVersion, declared oldest to newest:

use Mcp\Schema\Enum\ProtocolVersion;

ProtocolVersion::latestHandshake();   // newest revision reachable via `initialize`
ProtocolVersion::handshakeVersions(); // every revision the server will negotiate, oldest first
ProtocolVersion::modernVersions();    // every revision served without a handshake
ProtocolVersion::V2025_11_25->isAtLeast(ProtocolVersion::V2025_06_18); // true

Comparisons go through declaration order rather than string collation. The identifiers happen to be ISO dates today, but they are an enumerated set rather than an ordered scalar, so nothing should assume they sort chronologically.

How the server answers

Client requests Server responds with
A revision the server supports That same revision
An unknown or malformed revision ProtocolVersion::latestHandshake() as a counter-offer
A modern revision such as 2026-07-28 ProtocolVersion::latestHandshake() as a counter-offer

A counter-offer is not an error: the client decides whether it can continue on the offered revision or must close the connection. The negotiated revision is stored on the session under protocol_version.

The last row is not a rejection of an unknown revision — the SDK knows 2026-07-28, it just cannot be reached through this handshake. The modern era replaced initialize with per-request metadata, so answering with one of its revisions would leave a connection neither side could use. A client speaking it never gets here: it sends the envelope instead of an initialize request, and the transport routes it to the modern dispatcher before any negotiation is attempted. See Serving both eras.

Pinning a revision

Builder::setProtocolVersion() pins the handshake to exactly one revision instead of negotiating across the supported set. The pin wins over the client's request, so a client asking for anything else receives the pinned revision as a counter-offer and has to decide whether to continue. Leave it unset unless you have a reason to refuse other revisions.

It pins the handshake era only. setModernVersions() narrows what the modern leg answers for, and withoutModernEra() removes that leg altogether — see Serving one era only.

!!! note On the Streamable HTTP transport, every handshake-era request after the handshake also carries an MCP-Protocol-Version header. The transport checks this header against every revision in ProtocolVersion::handshakeVersions(), and the pin doesn't change that set. See Protocol Version Validation.

What changes, and where it is written down

Tools, resources, prompts and their handlers are unaffected — the same registrations serve either lifecycle. What changes:

  • Asking for input — a handler that needs elicitation, sampling or roots returns the ask instead of calling out. Write handlers this way and they serve both eras.
  • Serving both eras — what a modern request carries, how one endpoint classifies and routes each request, and how to serve one era only.
  • Caching — the ttlMs / cacheScope hints a cacheable result must carry.
  • Subscriptions — subscriptions/listen and the notification bus behind it.
  • Sessions — handshake-era only; the modern era has none.
  • Progress and logging become per-request opt-ins — see Talking back to the client and Logging.

Speaking it from a client

A client speaks both eras out of the box. It prefers 2026-07-28, and finds out on connect() whether the server does too; nothing about the client API depends on the answer.

$client = Client::builder()
    ->setClientInfo('my-client', '1.0.0')
    ->setCapabilities(new ClientCapabilities(elicitation: true))
    ->addRequestHandler($myElicitationHandler)
    ->build();

$client->connect(new HttpTransport('https://example.com/mcp'));

$client->getProtocolVersion(); // 2026-07-28, or 2025-11-25 against an older server
$client->callTool('greet', []);

How the client settles on an era

connect() probes with server/discover, stamped with the preferred revision, before anything else — as the specification's backward-compatibility rules for stdio and Streamable HTTP describe.

The probe gets The client
a DiscoverResult listing a modern revision it speaks stays modern, on that revision
-32022 naming a modern revision it speaks retries the probe with that revision
-32022 naming only handshake revisions falls back to initialize
-32022 naming nothing it speaks fails the connection
any other error, an HTTP refusal without one, or no answer in time falls back to initialize
a DiscoverResult listing only handshake revisions falls back to initialize

The fallback is not keyed to one error code: servers from before the modern era refuse an unexpected request however they like, or not at all. A refusal costs nothing — the client falls back as soon as it arrives — but a server that stays silent costs the initialization timeout. A server process that exits fails the attempt outright: an outage is not an answer about the era.

The fallback offers 2025-11-25; setFallbackProtocolVersion() picks another handshake revision, and setFallbackProtocolVersion(null) makes the client modern-only, failing the connection instead. A handshake revision passed to setProtocolVersion() skips the probe and opens with initialize, as a client from before the modern era would.

Once modern, a handful of calls change shape under the same API: setLoggingLevel() rides on every following request instead of sending the removed logging/setLevel, ping() becomes a server/discover, and sendRootsListChanged() sends nothing, since the server asks for roots with each call that needs them. A server can still ask for sampling and roots by returning the ask; calling out for them through ClientGateway is handshake-era only and fails the call on a modern connection.

What being modern changes underneath:

  • No handshake. connect() sends no initialize; the probe's DiscoverResult is what fills in the server's identity and instructions.
  • An envelope on every request, carrying the revision, the declared capabilities and the client identity. The capabilities are what let a server decide, per request, whether it may ask for input.
  • Headers on every POST — MCP-Protocol-Version, Mcp-Method, and Mcp-Name where the method addresses a subject. Arguments annotated with x-mcp-header are mirrored into Mcp-Param-*, which requires the client to have listed the tool first; tools/list is what populates that knowledge. A tool whose annotations are malformed is dropped from the listing and refused if called, since the client cannot produce the headers it demands.
  • Multi round-trip calls are answered by the client. A result of resultType: "input_required" is resolved through the same request handlers that served server-initiated requests in the handshake era, and the call is re-sent with inputResponses and the server's requestState echoed back byte for byte, under a new JSON-RPC id. The caller sees one call and one result.

Headers are an HTTP concern, so a transport opts into them by implementing HeaderAwareTransportInterface; HttpTransport does, StdioTransport has nothing to carry them on. Everything else — the probe, the envelope, the skipped handshake, the round-trip loop — applies to both.

See examples/client/stateless_lifecycle_client.php for a runnable version, described in Examples.

What was removed

Answered with 404 and -32601 by a modern server — except a bare initialize, which is how a client from before the modern era opens, and is refused with -32022 naming the revisions the server does speak:

  • initialize, notifications/initialized
  • ping
  • logging/setLevel — replaced by _meta["io.modelcontextprotocol/logLevel"]
  • resources/subscribe, resources/unsubscribe — replaced by the resourceSubscriptions filter of subscriptions/listen
  • notifications/roots/list_changed

Also gone: Mcp-Session-Id, the HTTP GET stream, and SSE resumability (Last-Event-ID). A broken response stream loses the request; the client re-issues it with a new id.

Error code -32002 (resource not found) is retired in favour of -32602, and must not be emitted by a server of this revision. The SDK picks the code from the revision serving the request, so a handshake-era client still gets -32002.

Deprecations

Roots, sampling and logging are all deprecated as of this revision (SEP-2577), earliest removal 2027-07-28. They remain functional until then; new servers should pass directories through tool arguments or resource URIs instead of roots, integrate with an LLM provider directly instead of sampling, and log to stderr or OpenTelemetry instead of notifications/message.