Skip to content

protocol-versions.md

Latest commit

 

History

History
178 lines (139 loc) · 9.48 KB

protocol-versions.md

File metadata and controls

178 lines (139 loc) · 9.48 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

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, which is validated separately by ProtocolVersionMiddleware. The pin does not reach that check: the transport builds the middleware without access to the server configuration, so the header keeps being accepted for every revision in ProtocolVersion::handshakeVersions(). To narrow it too, construct the middleware yourself with the same revision — 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

One line selects the lifecycle; nothing else about the client API changes.

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

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

$client->callTool('greet', []);

What that changes underneath:

  • No handshake. connect() sends no initialize. It asks server/discover only for the server's identity, and a server that does not answer it still yields a usable connection — the method is optional. If discovery does report supportedVersions and the configured revision is not among them, the client moves to a modern revision the server lists, or refuses the connection outright rather than talking past it.
  • 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 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:

  • 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.