When does the 2026-07-28 MCP specification ship?

The final 2026-07-28 specification publishes on July 28, 2026. The release candidate locked on May 21, 2026, and Tier 1 SDK support is expected within roughly a 10-week window around the final release.

What breaks when I migrate to the 2026-07-28 MCP spec?

The session handshake (initialize and Mcp-Session-Id) is removed, so servers become stateless. Roots, Sampling, and Logging are deprecated. The missing-resource error code changes from -32002 to -32602, and the Tasks API moved from experimental core to an official extension.

Why did MCP remove sessions?

Sessions forced sticky routing to a single server instance, a shared session store, and deep packet inspection at the gateway. Removing them lets each request carry protocol version and client info in _meta fields, so a stateless server can run behind a plain round-robin load balancer.

What replaces Roots, Sampling, and Logging?

Roots move to tool parameters, resource URIs, or config. Sampling is replaced by calling the LLM API directly from your server. Logging moves to stderr or OpenTelemetry. Each deprecated feature has a minimum 12-month removal window under the new Active to Deprecated to Removed lifecycle.

Do I need to change my error handling?

Yes if you check for specific codes. A missing resource now returns the standard JSON-RPC -32602 (invalid params) instead of -32002. Any hardcoded -32002 check will silently stop matching, so search your codebase and update it.

Migrate Your MCP Server to the 2026-07-28 Spec: What Breaks & How to Fix It

📖 TL;DR

The 2026-07-28 MCP spec is the largest revision since launch — the final spec ships July 28, 2026.
Sessions are gone. No initialize handshake, no Mcp-Session-Id header. Servers are stateless now.
Three features deprecated: Roots, Sampling, and Logging, each with a 12-month removal window.
One error code changed and JSON Schema 2020-12 is now fully supported.
Test your migrated server against a real model in MCP Playground before you ship.

The 2026-07-28 MCP spec is not a routine update. The maintainers call it the biggest revision since the protocol launched.

If you run a server built on the 2025-11-25 spec, some of it will break. Not maybe — will.

The good news: the changes are concrete and finite. This is a migration checklist, not a rewrite. I will walk through every breaking change and exactly what to do about it.

Let me start with the one that touches every remote server.

The headline change: your server is stateless now

The old protocol was stateful. A client opened a connection with an initialize handshake, got an Mcp-Session-Id, and every later request carried that session ID back.

That forced sticky routing. Requests had to hit the same server instance, backed by a shared session store, with deep packet inspection at the gateway.

The 2026-07-28 spec deletes all of it. There is no initialize handshake and no Mcp-Session-Id.

Instead, each request carries the protocol version and client info in _meta fields. Any instance in a load-balanced cluster can handle any request.

The payoff: a remote server that needed sticky sessions and a shared store can now sit behind a plain round-robin load balancer. I covered the concept in depth in MCP Goes Stateless — this post is about the migration itself.

What breaks: the migration checklist

Here is the full list of breaking changes, most impactful first.

Change	What to do
Session handshake removed	Drop `initialize` and `Mcp-Session-Id`; read version/client from `_meta`.
Roots deprecated	Move to tool parameters, resource URIs, or config.
Sampling deprecated	Call the LLM API directly from your server.
Logging deprecated	Emit to stderr or OpenTelemetry instead.
Error code changed	Missing resource is now `-32602`, not `-32002`.
Tasks API redesigned	Migrate from experimental core to the Tasks extension.

Three features are deprecated: Roots, Sampling, Logging

The spec added a formal deprecation lifecycle: Active → Deprecated → Removed, with a minimum 12-month window before anything disappears.

Three core features enter that pipeline now. They still work, but you should plan to move off them.

Roots → replace with tool parameters, resource URIs, or plain config. Pass the scope explicitly instead of relying on the roots capability.
Sampling → if your server asked the client to "sample" the model, call the LLM API directly instead. Cleaner and fewer round trips.
Logging → stop using the protocol log channel. Write to stderr or ship structured logs to OpenTelemetry.

Do not wait 12 months. The window protects you from a hard break, but new clients will optimize for the replacements. Migrating early means fewer compatibility surprises later.

The error code change that will bite you

This one is small and easy to miss. A missing resource used to return error code -32002.

In the 2026-07-28 spec it returns -32602 — the standard JSON-RPC "invalid params" code.

If your client has a hardcoded check for -32002, it will silently stop matching. Grep your codebase for that literal and update it.

New capabilities you get for free

Migration is not all removal. The spec adds infrastructure wins you can adopt.

Routable, Cacheable, Traceable headers

Routable: Mcp-Method and Mcp-Name headers let a gateway route without inspecting the body.
Cacheable: list responses carry ttlMs and cacheScope, so clients cache tool lists like HTTP Cache-Control.
Traceable: W3C Trace Context propagation is standardized across every SDK.

Full JSON Schema 2020-12

Tool input schemas now support the full JSON Schema 2020-12 draft. That means oneOf, anyOf, and allOf in your tool definitions.

If you were flattening complex inputs to work around the old limits, you can stop.

Authorization tightened up

Six auth proposals bring MCP closer to standard OAuth 2.0 and OpenID Connect.

Mandatory validation of the iss parameter, per RFC 9207.
OIDC application_type declared during client registration.
Clarified scope accumulation and refresh-token handling.

If you built auth against my OAuth 2.1 guide, review the iss validation rule — it is now required, not optional.

The timeline and how to test

The dates matter. The release candidate locked on May 21, 2026. The final spec publishes July 28, 2026.

Tier 1 SDK support is expected within the 10-week window around the final release. Check your SDK version before you assume a feature landed.

My migration order:

Update to a spec-compliant SDK build.
Strip session handling and read _meta instead.
Swap the deprecated features for their replacements.
Fix the -32002 → -32602 checks.
Run the server against a real model and confirm every tool still resolves.

Migrated to the 2026-07-28 spec?

Point a real AI model at your server and confirm every tool still works — no local setup.

Test any MCP server free →

How MCP Playground can help

The riskiest part of a migration is the stuff you did not know broke. A tool that stopped resolving. An auth flow that fails silently.

MCP Playground connects your server to a live model in the browser. You see every tool list, every call, and every error — so a regression shows up before your users hit it.

Frequently Asked Questions

When does the 2026-07-28 MCP spec ship? The final specification publishes on July 28, 2026. The release candidate locked on May 21, 2026.

Do I have to migrate right away? The stateless change affects new clients immediately, but deprecated features get a 12-month minimum window. Migrate early to avoid compatibility surprises.

What is the biggest breaking change? The removal of the session handshake and Mcp-Session-Id. Servers are stateless, so session-dependent code must be reworked.

Conclusion

The 2026-07-28 spec makes MCP stateless, deprecates Roots, Sampling, and Logging, and tightens auth. Update your SDK, strip sessions, swap the deprecated features, and fix the error code.

Then prove it works. Test any MCP server free against a real model before the final spec lands.