How to migrate an MCP server to the 2026-07-28 revision

MCP's 2026-07-28 revision is not an incremental field change — it removes the handshake. The modern era carries protocol version, capabilities, and identity on every request instead of negotiating them once at connection time. Treat migration as a compatibility rollout: detect a peer's era with the documented probes, keep authorization failures out of that detection, and hold traffic on any connection you have not verified — the specification itself is still unreleased.

0

initialize handshakes required per request in the modern era

3

new JSON-RPC error codes reserved for this revision

4

standard HTTP headers Streamable HTTP now requires

2

mechanisms removed from Streamable HTTP: sessions and the GET stream

This is a wire redesign, not a dependency bump

It is easy to read “protocol revision” and picture a few renamed fields. The MCP specification itself frames 2026-07-28 differently: it defines a “modern” era (2026-07-28 and later) that drops the initializehandshake entirely, and a “legacy” era (2025-11-25 and earlier) that keeps it. In the modern era, every request is self-contained — it carries its own protocol version, capabilities, and optional client identity in _meta, and a server processes each request independently with no state inferred from prior requests on the same connection.

The Streamable HTTP binding drops two things that shaped a lot of existing MCP deployments: the standalone GET SSE stream, and protocol-level sessions (Mcp-Session-Id). Server-to-client interactions — sampling, elicitation, roots — no longer arrive as independent JSON-RPC requests on an open stream; a server instead returns an InputRequiredResult, and the client retries the original request carrying the answer.

What changed on the wire

Detect a peer's era with the documented probe, not a guess

The specification treats era detection as a first-class, transport-specific mechanism — not something an integrator should reinvent per project.

• stdio: send server/discover first. A DiscoverResult means the server is modern; a recognized modern error (such as UnsupportedProtocolVersionError) means the server is modern but does not support the requested version — do not fall back to initialize; any other error, or no response within a reasonable timeout, means the server is legacy.
• Streamable HTTP: attempt a modern request first. On 400 Bad Request, inspect the response body. A recognized modern JSON-RPC error (UnsupportedProtocolVersionError, HeaderMismatch, MissingRequiredClientCapability) means the server is modern; an empty or unrecognized body means legacy — fall back to initialize.

Streamable HTTP also now mirrors several body fields into required headers — MCP-Protocol-Version, Mcp-Method, and, for tool, resource, or prompt calls, Mcp-Name — so that a gateway or load balancer can route and validate a request without parsing JSON. A mismatch between a header and the corresponding body value is rejected with HeaderMismatch (-32020), which means a proxy that rewrites one without the other will start breaking modern-era traffic it previously passed through untouched.

Do not let an authorization failure masquerade as a legacy peer

Era detection and authorization are separate facts in the specification, and it is worth keeping them separate in your own instrumentation too. The backward-compatibility mechanism above is scoped strictly to inspecting a 400 response body (HTTP) or a server/discover outcome (stdio). HTTP 401 and 403are not part of that mechanism at all — they are authorization outcomes, defined in MCP's separate authorization specification: 401 means authorization is required or the token is invalid, 403means the token's scopes are insufficient.

Build a compatibility matrix before you change traffic

Before shifting any real connection onto the modern era, inventory every peer that matters and record what you actually verified for it — not what the specification permits in principle.

This table is AgentOps Hardening: compatibility becomes a release decision backed by evidence, not an inference from a changed dependency. It is Bonfire's recommended method — the specification does not publish a universal matrix for every host or deployment topology.

Use a release gate that can hold or roll back

1. Record which era each connection actually negotiated, not which era you intended.
2. Assert the changed metadata shape directly: serverInfo in result _meta, not the body; clientInfo optional but rejected if malformed.
3. Exercise the required authorization path as its own test, separate from any era probe.
4. Keep the legacy handshake path passing until every required peer has verified modern-era evidence.
5. Give any failing matrix row an owner and a hold/rollback action before broadening traffic.

Pair this with the operational discipline in how to build a custom MCP server that survives production and the boundary questions in how to securely expose a private MCP server. Neither of those depends on which era a given connection speaks; this migration should not force you to relitigate them.

Scope and caveats

This is not a claim that 2026-07-28 is final, that every MCP implementation or SDK has adopted it, or that adoption will happen on any particular timeline. The specification content used here was read directly from the unreleased draft path of the official specification; it does not describe any specific SDK's package version, default client configuration, or API surface. Verify your own client, server, proxy, and transport combinations before treating any of them as migrated.