The MCP 2026-07-28 spec removes protocol-level sessions entirely, mandates two new HTTP headers, and deprecates three core primitives -- sampling, roots, and logging. Beta SDKs for Python, TypeScript, Go, and C# are live now. Server builders have until July 28 to migrate or risk breaking compatibility with every major MCP client.
I've been watching the MCP stateless migration thread since May, and this is the first time the spec has enough specificity to actually write code against. The RC locked on May 21, 2026 -- the July 28 final publish date is not slipping. If you're running a production MCP server, here's every change that will break your code and exactly how to handle it.
What Is the MCP 2026 Spec Actually Changing?
The 2026-07-28 release candidate is the largest MCP revision since launch. The core change: remote servers no longer need sticky sessions, a shared session store, or gateway deep packet inspection. A plain round-robin load balancer now works. The spec also ships MCP Apps, Tasks, and formally deprecates sampling, roots, and logging.
The RC was locked on May 21, 2026, giving SDK maintainers a ten-week validation window before the final spec publishes on July 28, 2026 (source: MCP Blog). Tier 1 SDKs are already in beta. The Python SDK shipped as mcp 2.0.0b1 on PyPI. The TypeScript SDK ships under new package names at 2.0.0-beta.1, separate from the v1 package that stays on its 1.x line (source: SDK Betas announcement). Go and C# betas are also live.
The protocol touches four areas: the HTTP transport layer, the per-request envelope, the caching model, and three primitives being removed. Below is each change and what your code needs to do about it.
Breaking Change #1: Mcp-Session-Id Is Gone
The Mcp-Session-Id header and the protocol-level session it represents are removed in the 2026 spec (SEP-2567). Any server instance can now handle any request because protocol version, client identity, and capabilities travel in a _meta object on every request, instead of being negotiated once at connection time.
If you've been keying state off Mcp-Session-Id, move to an explicit handle pattern: the client passes a handle in, the server passes a handle back, and your actual state lives in Redis, Cosmos, or any external store you already manage. The server itself becomes stateless at the protocol layer -- the same pattern used by every modern REST API.
The practical win: you can now run your MCP server behind a standard AWS ALB or Nginx upstream with round-robin routing. No sticky sessions, no shared memory session store, no gateway doing deep packet inspection to route requests to the right pod. If you've ever tried to scale a multi-replica MCP deployment, this is the change you've been waiting for.
Breaking Change #2: Two New Required HTTP Headers
Every Streamable HTTP request now requires Mcp-Method and Mcp-Name headers (SEP-2243). These tell load balancers, gateways, and rate limiters which operation is being called without body inspection. If you're writing server middleware or built your own MCP gateway, these headers need to be forwarded and validated.
On the server side, validate that both headers are present on every Streamable HTTP request. On the gateway side, you can now route Mcp-Method: tools/call to a high-memory instance tier and Mcp-Method: tools/list to a cheap cache layer without parsing any JSON bodies. For high-traffic MCP deployments, this is where the real performance gains show up.
Breaking Change #3: The Initialize Handshake Is Removed
The initialize request and notifications/initialized message are gone from the 2026 spec. Client identity, protocol version, and capabilities that used to be exchanged in that handshake now travel in a _meta object on every request, under keys like io.modelcontextprotocol/protocolVersion, /clientInfo, and /clientCapabilities.
If your server logic gates on the initialize handshake -- checking client capabilities before responding to tool calls -- that code needs to move to per-request checking against _meta. The upside: your server no longer has a cold-start problem where the first request must be an initialize before any useful work happens. Implement server/discover as the replacement mechanism for clients that need server metadata before issuing requests.
Breaking Change #4: Add ttlMs and cacheScope to List Responses
The 2026 spec formalizes caching semantics for tools/list and resource reads. Servers can now attach ttlMs to list responses so clients and gateways know how long to cache them. A companion cacheScope field controls whether the cache is per-client or shared. This is new behavior, not a removal -- but omitting ttlMs means leaving free performance on the table.
For static tool lists -- which most MCP servers have -- set ttlMs: 86400000 (24 hours). Claude Code currently calls tools/list on every new conversation session. With proper ttlMs set, a CDN or gateway can serve that response from cache for the day without touching your server. For tool lists that vary by auth state, use ttlMs: 300000 (5 minutes) and cacheScope: "client". For fully static tool lists, use cacheScope: "shared".
Breaking Change #5: W3C Trace Context Is Now Locked in _meta
Distributed trace propagation via W3C Trace Context is now formally specified (SEP-414). The traceparent, tracestate, and baggage keys in _meta are locked down with stable names. This matters if you're running multiple MCP servers in a chain or correlating traces across an agent's tool calls in Datadog, Honeycomb, or any OpenTelemetry backend.
If you already propagate traceparent, make sure you're reading it from _meta rather than HTTP headers directly. If you haven't wired up distributed tracing yet, the spec now guarantees the key names -- so any instrumentation you add will work consistently across all compliant MCP clients.
Breaking Change #6: Sampling, Roots, and Logging Are Deprecated
The 2026 spec formally deprecates three primitives: sampling (a server asking a client to generate a completion), roots (listing filesystem roots), and logging (structured log emission via the protocol). Deprecated means the spec no longer requires clients to support them, and client support can be dropped in future revisions.
If you have production servers using any of these three, they won't break on July 28 -- but the migration clock is running. Sampling is the most complex to replace if you've built orchestration logic that relies on it. The spec's position: sampling creates tight coupling between server and model choice, which breaks the composability that makes MCP useful. Replace sampling with explicit tool chaining in your orchestration layer. Roots and logging have straightforward application-layer alternatives.
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
What's New: MCP Apps and the Tasks Extension
The 2026 spec ships two major new capabilities alongside the breaking changes. MCP Apps (SEP-1865) lets servers ship interactive HTML interfaces that clients render in a sandboxed iframe. The Tasks extension enables long-running agent work via a handle-based lifecycle that fits the stateless model -- no held-open connections required.
MCP Apps is worth understanding if you build tools that are awkward to invoke via text prompts. Your server declares HTML UI templates alongside its tools. The MCP client host renders them in a sandboxed iframe -- no separate web server, no separate auth flow. Every button click in that iframe triggers a standard MCP tool call that goes through the client's normal consent path. It renders automatically inside Claude Code, Cursor, or any MCP-compliant host. This is useful for approval UIs, form-based configurators, and any tool where the text interface creates friction.
Tasks reshapes long-running work. Instead of holding open a connection while an agent runs, a server answers tools/call with a task handle. The client drives it with tasks/get, tasks/update, and tasks/cancel. If you shipped against the 2025-11-25 experimental Tasks API, you need to migrate -- that lifecycle doesn't carry forward. The new lifecycle is cleaner: task creation is server-directed, and the client polls rather than the server pushing.
The Migration Checklist: Six Steps Before July 28
Here's the exact checklist I'd run against any production MCP server today. Priority order -- start from the top because the session removal and new header requirements are the changes that break client compatibility first. All six need to be complete before July 28.
Step 1: Install the v2 SDK beta. Python: pip install mcp==2.0.0b1. TypeScript: use the new 2.0.0-beta.1 package names, not the v1 package. Go and C# betas are also available. Don't wait for the stable release -- validate against the beta now so you're not scrambling the week of July 21.
Step 2: Remove all Mcp-Session-Id logic. Search your codebase for Mcp-Session-Id and mcp_session_id. If you have zero session state (most read-only tools don't), you're already done. If you do maintain state keyed on session ID, move it to an explicit handle pattern with your external state store.
Step 3: Add Mcp-Method and Mcp-Name header validation. Add middleware that requires these headers on every Streamable HTTP request. Log them from day one -- they're useful for debugging and building request-level metrics before you wire up gateway routing.
Step 4: Move capability checks from initialize to _meta. If your server gates behavior on client capabilities, update that logic to read from _meta on each request. No capability-gating logic in your server? Skip this step.
Step 5: Add ttlMs to all list responses. Static tool lists: ttlMs: 86400000 and cacheScope: "shared". Auth-dependent tool lists: ttlMs: 300000 and cacheScope: "client". This is the easiest performance win in the spec and takes under five minutes to add.
Step 6: Audit deprecated primitives. Grep for sampling, roots, and logging in your server implementation. Flag any hits. They won't break July 28, but you want a migration plan before client support starts dropping.
When to Start and What to Test
Start the migration this week, not the week of July 21. The beta SDKs are stable -- the RC was locked May 21 and the betas are tracking it closely. Starting now gives you two weeks of runway if you hit unexpected behavior in the SDK betas or discover session state assumptions you missed.
For testing, the most important scenario is statelessness under load: run two instances of your server behind a round-robin load balancer, fire 100 requests at it, and verify responses are consistent regardless of which instance handles each request. If they're not, you have session state that didn't get migrated to the handle pattern.
The second test: verify a client can complete a full tool call lifecycle -- discover, list, call, result -- without an initialize handshake. If your server errors on the first non-initialize request, the handshake removal didn't land correctly in your implementation.
Test the Tasks cancel path specifically if you're adopting the Tasks extension. That's where edge cases surface first in any async job system -- cancel races, partial results, and timeout behaviors are the scenarios the happy-path tests miss.
FAQ
What breaks on July 28 if I don't migrate my MCP server?
Your server won't stop working the moment the spec publishes on July 28 -- clients need time to ship v2 protocol support. The real break comes when major MCP clients drop support for the old session-based protocol in a future update. The ten-week SDK window closes around July 28, but client v2 adoption will roll out over weeks that follow. Migrate now to stay ahead of that rollout rather than reacting when a client update breaks your users.
Do I need to rewrite my MCP server from scratch for the 2026 spec?
No. The six changes are all additive or targeted swap-outs: remove Mcp-Session-Id, add Mcp-Method/Mcp-Name headers, update _meta reads, add ttlMs. If you're using a Tier 1 SDK (Python or TypeScript), upgrading to the 2.0.0 beta package handles most of the heavy lifting. The biggest real work is migrating session state to an external store -- and that only applies to servers that maintain stateful session logic, which many don't.
What does MCP Apps actually look like in practice?
MCP Apps (SEP-1865) lets your server declare an HTML interface alongside its tools. The MCP client host renders it in a sandboxed iframe -- no separate web server, no separate auth flow. Every button click in that iframe triggers a standard MCP tool call through the client's normal consent path. Useful for approval UIs, form-based configurators, and preview panes for agent actions -- any tool where the text prompt interface creates confusion or friction.
Is the new Tasks extension the same as the experimental Tasks API from 2025-11-25?
No -- the Tasks extension is a redesign. The 2025-11-25 experimental API got enough production feedback to warrant a clean lifecycle. In the new design, the server answers tools/call with a task handle and the client drives it with tasks/get, tasks/update, and tasks/cancel. Task creation is server-directed. The old experimental response shape does not carry forward, so migration is required if you shipped against it.
Which SDKs have v2 beta support for the 2026-07-28 MCP spec?
Four SDKs have beta builds: Python (mcp 2.0.0b1 on PyPI), TypeScript (2.0.0-beta.1 under new package names separate from the v1 line), Go, and C#. The TypeScript v1 package stays on its 1.x line and will not receive v2 features, so if you're on TypeScript make sure you're pulling from the new package name. Source: MCP SDK Betas blog post.
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