The MCP 2026-07-28 spec ships today, removing the initialize handshake, dropping the session ID header, renaming the TypeScript SDK packages, and formally deprecating Roots, Sampling, and Logging. Any MCP server running the 2025-11-25 protocol needs to evaluate these changes before clients start failing. Here is the migration checklist.
I watched the RC land three days ago and have been tracking the GitHub issues since. The July 25 article covered what was coming -- now that the spec is live, this is the authoritative guide to what actually changed, what code you need to update, and what you can safely defer.
What exactly breaks today -- the stateless core change
The biggest breaking change: the initialize/initialized handshake is gone (SEP-2575) and the Mcp-Session-Id header is gone with it (SEP-2567). Protocol version, client info, and capabilities no longer travel once at connection time -- they travel in _meta on every request. Any server that expects an initialize message before serving requests will reject v2 clients.
This affects every MCP server that uses sticky load balancer routing, shared Redis session stores, or gateway-level session state. The silver lining: you can now run MCP behind a plain round-robin load balancer without body inspection. No more session affinity configuration.
Two new required HTTP headers ship alongside the stateless core: Mcp-Method and Mcp-Name. These let load balancers and API gateways route requests by operation type without parsing the JSON body. If your gateway does header-based routing, you need to add these. If it does body inspection today, you can simplify by switching to header routing.
The GitHub MCP Server already declared support for the next spec as of July 23, 2026 -- that is how close the ecosystem is to flipping. If one of the largest MCP server deployments is already there, clients will start sending v2 traffic sooner than you expect.
How to update your server to handle v2 requests
A v2 server must handle two things: respond to server/discover (the replacement for the initialize handshake), and accept requests where capabilities arrive in _meta rather than from a prior initialize exchange. The good news -- a v2 server can still answer the legacy initialize handshake, so existing v1 clients keep connecting during your transition window.
Here is the before-and-after for server capability negotiation. Under the old spec, your server waited for initialize, stored the client capabilities, then served requests. Under the new spec, expose capabilities via server/discover and read client capabilities from _meta.clientInfo on each incoming request:
# Old flow (2025-11-25)
# 1. Client sends initialize
# 2. Server stores session state
# 3. Client sends initialized
# 4. Server serves requests using stored session
# New flow (2026-07-28)
# 1. Client optionally calls server/discover upfront
# 2. Every request carries _meta.clientInfo + _meta.capabilities
# 3. Server reads capabilities per-request, no session state needed
For HTTP transports, add Mcp-Method and Mcp-Name to your response headers. For stdio transports, these headers are not applicable -- stdio servers are not behind load balancers and are unaffected by this change.
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
The SDK migration: Python and TypeScript both have breaking changes
The Python SDK beta installs as pip install "mcp[cli]==2.0.0b1". The API surface is largely compatible but the session management code is gone, and any imports that reference session handling will break. For most servers that means removing the session middleware layer and reading client capabilities from request context instead.
The TypeScript migration is more disruptive because it is a package rename, not a version bump. The old @modelcontextprotocol/sdk stays on v1. The new packages are @modelcontextprotocol/server and @modelcontextprotocol/client, both at version 2.0.0-beta.1. You cannot just bump a version number -- you need to update your imports and package.json dependencies.
# TypeScript migration
# Remove old package
npm uninstall @modelcontextprotocol/sdk
# Install new split packages
npm install @modelcontextprotocol/server@2.0.0-beta.1
npm install @modelcontextprotocol/client@2.0.0-beta.1
# Update imports
# OLD:
import { McpServer } from "@modelcontextprotocol/sdk/server";
# NEW:
import { McpServer } from "@modelcontextprotocol/server";
One important note from the official SDK blog: upgrading the SDK does not automatically switch your server to the v2 protocol revision. You choose when to adopt v2 behavior. A server running the new SDK can still speak 2025-11-25 to clients that have not updated yet.
What is deprecated but not removed -- Roots, Sampling, and Logging
SEP-2577 formally deprecates three MCP features: Roots, Sampling, and Logging. Deprecated means they still work but are on the removal track. The spec adopts a formal deprecation policy (SEP-2596) guaranteeing a minimum 12-month window between a feature being marked Deprecated and becoming eligible for Removal. Security exceptions can shorten this to 90 days, but that applies only to active security issues.
The recommended replacements are: explicit tool parameters or resource URIs for Roots; direct LLM provider API integration for Sampling; and stderr for stdio transports or OpenTelemetry for structured observability in place of Logging. None of these replacements are drop-in -- they require intentional migration -- but you have at least 12 months to do it.
If your server currently uses sampling (letting the server request the client to make LLM calls on its behalf), this is the most significant work item. The v2 model pushes LLM calls to be the server's own responsibility -- your server calls the LLM provider directly rather than delegating through the client. That changes your auth model, your cost model, and your latency profile.
New features shipping with the spec -- Tasks, MCP Apps, OAuth 2.1
Three new capabilities graduate to first-class status in the 2026-07-28 spec, and they are worth knowing even if you do not need them immediately.
The Tasks extension handles long-running operations cleanly. A server can respond to tools/call with a task handle instead of blocking the connection. The client then drives the task with tasks/get, tasks/update, and tasks/cancel. This is the correct pattern for any tool call that takes more than a few seconds -- file processing, code execution, API calls with rate limits. Previously, servers had to either block the connection or implement their own polling endpoints.
MCP Apps allows servers to ship interactive HTML interfaces that MCP hosts render in a sandboxed iframe. This is early-stage but it opens the door to servers that expose rich configuration UIs, approval workflows, or visual outputs directly inside the client interface without requiring the user to leave.
The OAuth 2.1 hardening is the most enterprise-relevant addition. MCP servers are now formally OAuth 2.1 resource servers. Servers must implement Protected Resource Metadata (RFC 9728) so clients can auto-discover the correct authorization server. Clients must implement Resource Indicators (RFC 8707) to scope tokens to a specific server -- this closes the attack where a malicious server obtains tokens meant for a different server. If you are building MCP into any multi-tenant or enterprise context, these two RFC requirements are not optional.
Is your server actually affected -- a quick audit checklist
Most public MCP servers fall into one of three categories: stdio-only servers that are minimally affected, HTTP servers that need stateless migration work, and servers that use deprecated features that need longer-term remediation. Running through this takes about 10 minutes.
Run these checks against your server codebase:
# Check for session-related code
grep -r "Mcp-Session-Id\|initialize.*handshake\|session_id" ./src
# Check for deprecated feature usage
grep -r "sampling\|roots\|logging" ./src/mcp
# Check which SDK version you are on
# Python:
pip show mcp
# TypeScript:
cat package.json | grep modelcontextprotocol
If the session grep returns results and you are running an HTTP server, you have breaking changes to address. If the deprecated feature grep returns results, you have 12 months but should start planning now. If you are stdio-only and do not use Roots, Sampling, or Logging, you are largely unaffected by the stateless core change.
The 97 million monthly SDK downloads that flow through the MCP ecosystem mean that client-side updates will arrive faster than you might expect. Claude Desktop, Cursor, VS Code, and other major MCP hosts are all tracking the v2 spec -- some will begin advertising v2 capabilities within weeks of the stable release.
FAQ
Will v1 MCP servers break immediately when clients update to v2?
No, not immediately. A v2 client is required to support the legacy initialize handshake for backward compatibility. Your v1 server will continue to receive traffic. However, v2-only features like Tasks and MCP Apps will not be available to v1 servers, and at some point clients may drop the legacy handshake. The 12-month deprecation window on the old spec gives you a firm deadline.
Do I need to migrate if I only use stdio transport?
The stateless core change -- removing the initialize handshake and Mcp-Session-Id -- applies to all transports. Stdio servers do not have HTTP headers, so the Mcp-Method and Mcp-Name header requirements do not apply. If your stdio server does not use Roots, Sampling, or Logging, the migration effort is minimal: update to the new SDK package names and remove any session-state handling from your code.
What is the fastest path to v2 compliance for a production HTTP server?
Install the SDK beta, implement server/discover alongside your existing initialize handler, move capability reading from session state to per-request _meta parsing, and add Mcp-Method and Mcp-Name to your HTTP responses. A server that does all four can serve both v1 and v2 clients simultaneously during the transition window. The TypeScript package rename requires a dependency update and import path changes, but no API surface changes beyond the session removal.
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