Skip to content
MCP 2026-07-28: What Breaks and How to Migrate Your Server
TutorialsSeptember 8, 202612 min read

MCP 2026-07-28: What Breaks and How to Migrate Your Server

The MCP 2026-07-28 spec removes sessions, deprecates Roots/Sampling/Logging, and adds MRTR. Here is what breaks and how to migrate your MCP server in 4 steps.

The MCP 2026-07-28 spec is the biggest protocol change since MCP launched. It removes the initialize handshake, drops session IDs, deprecates Roots, Sampling, and Logging, and adds MRTR, MCP Apps, and a formal Tasks extension. Old servers that rely on session state will break. Here is the exact migration path.

I have been tracking the MCP spec since the release candidate dropped in early July. If you have MCP servers in production, the July 28 final spec requires real changes -- not just version bumps. Here is what I found running through the breaking changes and the official migration docs.

What exactly changed in the MCP 2026-07-28 spec?

The 2026-07-28 MCP spec removes the session layer entirely. The initialize/initialized handshake is gone. The Mcp-Session-Id header is gone. Every request is now self-describing -- it carries the protocol version and client identity in _meta. This turns MCP servers into stateless HTTP services that can sit behind a plain round-robin load balancer without shared storage or sticky sessions.

This is the most substantive MCP change since authorization support was added. Before July 28, MCP assumed a single stateful connection between client and server. The session handshake was mandatory. Any server handling multiple clients needed careful session tracking. That entire model is replaced with a stateless core where any instance can serve any request.

Three new required headers do the routing work that sessions previously handled: Mcp-Method (the operation name), Mcp-Name (the server name), and the W3C traceparent. Gateways and firewalls can now inspect MCP traffic without parsing JSON bodies -- a major operational improvement. Cloudflare already uses a variant of this approach: their Code Mode MCP Server scaled to thousands of requests per second and served billions of tool calls since February 2026 (Cloudflare blog).

The official Tier 1 SDKs -- TypeScript, Python, Go, and C# -- have all shipped updates for the 2026-07-28 spec. Rust is in beta. For context on why this spec change matters at scale: the TypeScript and Python SDKs each surpassed 1 billion total downloads, and all Tier 1 SDKs collectively reach around 500 million monthly downloads (MCP blog). That is a large footprint for a breaking change.

Community

Stop building alone.

Join the Skool community. Ask questions, share what you're building, and learn from other people actually shipping AI agents.

Join Skool →

What breaks? The three categories of breakage

Breaking changes in the 2026-07-28 spec fall into three buckets: session state that the protocol no longer carries, deprecated features that stop receiving new capabilities, and transport deprecations that will strand some existing clients as the ecosystem moves on. A 12-month deprecation window means nothing is immediately removed -- but the clock is running on everything in this list.

Session-dependent state

The most impactful break. If your server stores any data scoped to an Mcp-Session-Id -- user preferences, in-flight context, accumulated tool results -- that state now needs to live somewhere else. The spec moves session context to a client-held opaque handle. Your server instance is expected to be stateless; external stores (Redis, a database, the client payload itself) now own any per-session data.

Servers that used initialize to negotiate capabilities also break. The capability negotiation model is removed from the protocol layer entirely. Feature detection happens through other mechanisms in the new spec.

Deprecated: Roots, Sampling, and Logging

Three features moved from core to deprecated status. They still work -- the deprecation policy guarantees a minimum 12-month window from the deprecating revision before anything becomes eligible for removal, per the official changelog. But new implementations should not adopt them, and existing implementations should migrate while the window is open.

The migration paths are direct: replace Roots with directory or file parameters in tool calls or server configuration; replace Sampling by calling LLM provider APIs directly; replace Logging with stderr output (stdio servers) or OpenTelemetry.

Transport deprecation

Legacy HTTP+SSE transport is deprecated with the same 12-month minimum window. Old clients that only speak legacy HTTP+SSE will not be able to connect to new servers that have dropped it. The transition window exists so you can run both transport paths simultaneously while the ecosystem moves forward.

Dynamic Client Registration (DCR) is also deprecated, replaced by Client ID Metadata Documents (CIMD). The auth model received a broader hardening pass: RFC 9207 issuer validation is now required before code redemption, and client credentials are bound to the issuing authorization server.

Want the templates from this tutorial?

I share every workflow, prompt, and template inside the free AI Creator Hub on Skool. 500+ builders sharing what actually works.

Join Free on Skool

How do you migrate your MCP server to the 2026-07-28 spec?

Migrating to the 2026-07-28 spec has four concrete steps: remove the initialize handshake, externalize any session state, add the three required headers, and update or remove deprecated features. If you are on a Tier 1 SDK, version updates handle most of the low-level protocol changes. Custom servers need to handle each piece manually.

Step 1: Remove the initialize handshake

Stop handling initialize requests as the mandatory first message. The new spec sends protocol version and client identity in _meta on every request. Update your request parsing to read from there instead of from accumulated session state.

// Before: session-scoped initialization
server.on('initialize', (req) => {
  sessions[req.sessionId] = { clientInfo: req.params, tools: [] }
})

// After: read from _meta on each request
const clientVersion = req._meta?.protocolVersion
const clientInfo = req._meta?.clientInfo

Step 2: Externalize session state

Anything your server stores by session ID needs a new home. For simple use cases, the client can carry state as an opaque token in each request. For complex cases -- long-running agent sessions, accumulated tool results -- use an external store. Redis works. A database works. The hard constraint: your server instance must handle any request without local state from prior requests on the same connection.

Step 3: Add the three required headers

Your server needs to emit -- and clients need to send -- Mcp-Method, Mcp-Name, and traceparent on every request. If you are behind a gateway or running in a serverless environment, these headers enable routing and observability without JSON body inspection. This is what makes MCP traffic behave like any standard HTTP API for your infrastructure layer.

Step 4: Update or remove deprecated features

Roots: replace with explicit parameters or server configuration. Sampling: call your LLM API directly. Logging: switch to stderr or OpenTelemetry. Legacy HTTP+SSE: keep running for existing clients while you add the new transport path for new clients. Do not remove legacy support before your client population has migrated.

If you are on the TypeScript or Python SDK, start with the version update -- the Tier 1 SDKs ship migration helpers that handle header negotiation and _meta parsing. The createMcpHandler API simplifies the transition considerably. Run your test suite after the update; failing tests surface your session-state dependencies more precisely than manual auditing.

What is new in the spec that is actually worth using?

The 2026-07-28 spec is not only removals. Multi Round-Trip Requests (MRTR), MCP Apps, the official Tasks extension, and cacheable list results add real capabilities -- all designed for the stateless model. If you are rebuilding your server for the new spec, these are the features worth understanding now rather than discovering later.

MRTR: server-initiated input without a held-open stream

Multi Round-Trip Requests replace the old elicitation pattern. Previously, getting user input mid-call required a held-open stream -- impossible in a stateless model. MRTR fixes this: the server returns an input_required result, the client collects the needed information, and the client retries with it. No persistent connection needed. This enables clarification questions, confirmation dialogs, and multi-step forms inside tool calls without abandoning the stateless architecture.

MCP Apps: HTML in a sandboxed iframe

MCP Apps are server-rendered HTML interfaces that run in a sandboxed iframe inside the client. Tools declare their UI templates upfront, so clients can prefetch and security-review them before rendering. UI actions -- button clicks, form submissions -- flow back through the same JSON-RPC channel as regular tool calls. No separate WebSocket or iframe message protocol required.

The official ext-apps repository has working examples across multiple categories: 3D visualizations (threejs-server), data exploration (cohort-heatmap-server, wiki-explorer-server), business tools (scenario-modeler-server, budget-allocator-server), and utilities (qr-server, transcript-server). If your tools currently return long JSON blobs or markdown tables that clients render awkwardly, MCP Apps is the intended path forward (MCP Apps docs).

Tasks extension: stateless long-running operations

Tasks moved from experimental core to an official extension after production use drove a redesign. The new lifecycle fits the stateless model: tools/call returns a task handle, and the client drives progress by polling with tasks/get, updating with tasks/update, or canceling with tasks/cancel. No subscription model, no held-open stream. If you are building agents that run operations over minutes -- code execution, file processing, multi-step pipelines -- the Tasks extension is the right primitive now.

Cacheable list results

Tools/list, prompts/list, resources/list, and resources/read now include ttlMs and cacheScope parameters. Return a reasonable TTL on your capability lists and clients skip the re-fetch overhead on every request. For high-traffic servers, this is one of the fastest performance wins available in the new spec -- add a few fields to your existing list responses and you are done.

When should you migrate, and in what order?

The 12-month deprecation window means deprecated features are eligible for removal starting in July 2027 -- but eligible is not the same as immediately removed. The practical timeline for legacy HTTP+SSE disappearing is probably 18-24 months from now. That said, building new functionality on top of deprecated primitives means paying double migration cost later. Here is the priority order I would use.

Immediate: Update your Tier 1 SDK to the 2026-07-28 version and add the three required headers. This is the minimum needed to maintain compatibility with new clients without breaking old ones. On a Tier 1 SDK, this is an afternoon of work.

Next sprint: Remove the initialize handshake and externalize session state. This is the architecturally significant change. Once done, your server can deploy to serverless infrastructure -- Cloudflare Workers, AWS Lambda, any platform -- without complexity around sticky sessions or shared state stores at the protocol layer. Stateless deployment is the main operational win of this spec change and it compounds over time as your deployment footprint grows.

Before year-end: Migrate away from Roots, Sampling, and Logging. These still work, but shipping new features against deprecated primitives is a mistake. Start new functionality on the replacement patterns now so you are not doing two migrations later.

David Cramer, co-founder of Sentry, put it plainly after deploying to production before the spec was finalized: "This new spec cleans up a bunch of the nonsense around auth and tools." Sentry was willing to take the pre-release risk, which signals how stable the spec was well before July 28. If your production risk tolerance is lower than Sentry's, the final spec is that much more justification to move now.

FAQ

Do my existing MCP servers break immediately after July 28, 2026?

No -- existing MCP servers do not break immediately. The 12-month deprecation window means Roots, Sampling, Logging, legacy HTTP+SSE, and DCR all remain functional until at least July 2027. However, servers using the initialize handshake and Mcp-Session-Id become incompatible with new clients that only speak the 2026-07-28 spec unless you add a backward-compatibility layer. The real risk is not breakage today -- it is client ecosystem drift over the next 6-12 months as new clients stop supporting the old protocol path.

What is the simplest way to check if my server needs migration work?

Run four checks: Does your server require an initialize handshake before accepting other requests? Does it track per-session state keyed to Mcp-Session-Id? Does it use Roots, Sampling, or Logging? Does it use legacy HTTP+SSE transport? If you answered yes to any of these, you have migration work ahead. If you are on a Tier 1 SDK (TypeScript, Python, Go, C#), update the package and run your tests first -- the SDK handles lower-level protocol changes, and failing tests surface your session-state dependencies precisely.

How does MRTR replace the old elicitation model?

In the old model, getting user input mid-call required a held-open connection: the server sent a request back over the active stream, and the client responded on that same stream. In the stateless model, that is impossible. MRTR uses a polling pattern instead: the server returns an input_required result with a handle, the client collects the information from the user, and the client retries the original call with the collected data attached. The server holds nothing open. Any stateless instance can process the retry without knowledge of what came before.

Should I implement MCP Apps now?

Worth evaluating now if your tools produce output that benefits from visual representation -- dashboards, data tables, maps, forms, confirmation dialogs. The sandboxed iframe model is well-specified and the official ext-apps repository has working examples you can run today. If your tools return long JSON strings or markdown tables that clients render awkwardly, MCP Apps gives you server-controlled rendering without requiring client-side code changes. All UI actions flow through the existing JSON-RPC channel, so there is no new security surface to audit on the client side.

Want the templates from this tutorial?

I share every workflow, prompt, and template inside the free AI Creator Hub on Skool. 500+ builders sharing what actually works.

Join Free on Skool
AI Agents First

The daily signal from the frontier of AI agents.

Join builders, founders, and researchers getting the sharpest one-email read on what's actually shipping in AI — every morning.

No spam — unsubscribe anytime