# Migrate Your MCP Server to the 2026-07-28 Spec: What Breaks & How to Fix It > The 2026-07-28 MCP spec is the biggest revision since launch. Sessions are gone, three features are deprecated, and error codes changed. Here is the migration checklist. **Source:** https://mcpplaygroundonline.com/blog/migrate-mcp-server-2026-07-28-stateless **Author:** Nikhil Tiwari **Published:** 2026-07-22 **Category:** Development **Reading time:** 11 min read --- 📖 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](/mcp-test-server) 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](/blog/mcp-stateless-2026-release-candidate) — 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](/blog/mcp-tasks-extension-long-running-operations). ## 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](/blog/mcp-server-oauth-authentication-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: 1. Update to a spec-compliant SDK build. 2. Strip session handling and read `_meta` instead. 3. Swap the deprecated features for their replacements. 4. Fix the `-32002` → `-32602` checks. 5. 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 →](/mcp-test-server) ## 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](/mcp-test-server) 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](/mcp-test-server) against a real model before the final spec lands. ## Frequently asked questions ### 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. --- _Canonical page: https://mcpplaygroundonline.com/blog/migrate-mcp-server-2026-07-28-stateless — MCP Playground (mcpplaygroundonline.com), the free browser-based tool for testing MCP servers and building AI agents._