Mcp 2026 Migration

MCP 2026-07-28 Migration (Stateless Core, MRTR, CIMD)

This skill is an operating procedure for moving MCP servers, gateways, and clients from protocol 2025-11-25 (or earlier) to 2026-07-28 — which the maintainers call MCP's most important release since remote MCP first launched. It gives you the exact headers, _meta keys, result fields, error codes, and deprecation offramps from the official spec and the maintainers' deep-dive, plus a per-role migration checklist.

When to use

• Upgrading an existing MCP server, client, or SDK integration to protocol version 2026-07-28.
• Writing any NEW MCP implementation (start on the new patterns; do not adopt deprecated features).
• Configuring gateways, load balancers, rate limiters, or WAFs in front of MCP servers.
• Debugging UnsupportedProtocolVersion (-32022), HeaderMismatch (-32020), or session-related breakage after an SDK upgrade — the blog notes the migration cost lands hardest on developers who depended on session identifiers.

Do NOT use when the deployment is deliberately pinned to 2025-11-25 or earlier with no upgrade planned, or for OAuth work unrelated to MCP. Do not use it to justify ripping out deprecated features immediately — Roots, Sampling, and Logging keep working for at least twelve months under the formal deprecation policy.

Rules

Stateless core

1. Remove the initialize/notifications/initialized handshake and the Mcp-Session-Id header entirely (SEP-2575, SEP-2567). Every request must carry its protocol version and client capabilities in _meta: io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities. Clients SHOULD add io.modelcontextprotocol/clientInfo per request; servers SHOULD return io.modelcontextprotocol/serverInfo in each result's _meta. Why: any request can now land on any server instance behind a plain round-robin load balancer with no shared storage.
2. Servers MUST implement the server/discover RPC advertising supported versions, capabilities, and identity. Clients MAY call it up front for version selection or as a backward-compatibility probe on STDIO. Version mismatches return UnsupportedProtocolVersionError (-32022).
3. Protocol sessions are gone but application state is not: have a tool mint an explicit state handle and require the model to pass it back as an ordinary tool argument on later calls (the maintainers' recommended pattern). List endpoints (tools/list, resources/list, prompts/list) no longer vary per-connection.

Header-based routing

1. Every Streamable HTTP POST MUST carry MCP-Protocol-Version and Mcp-Method (the RPC method); Mcp-Name (from params.name or params.uri) is additionally REQUIRED on tools/call, resources/read, and prompts/get requests (SEP-2243). Header/body mismatch — or a missing/malformed required header — is HeaderMismatchError (-32020). Custom headers come from tool parameters annotated with x-mcp-header in the tool's inputSchema, mirrored as Mcp-Param-{Name} headers.
2. Gateways should, per the maintainers, "route and meter on those headers instead of parsing JSON bodies" — apply routing, rate limits, and WAF rules at the header layer.

Multi Round-Trip Requests (MRTR)

1. Server-initiated requests (roots/list, sampling/createMessage, elicitation/create) are no longer supported — breaking change (SEP-2322). Instead, respond to the client's request with an InputRequiredResult: resultType: "input_required", an optional inputRequests map, and an optional requestState string. At least one of the two MUST be present.
2. inputRequests keys are server-assigned identifiers, unique within the request; values MUST be one of ElicitRequest, CreateMessageRequest, or ListRootsRequest. Never include a request type the client did not declare in its capabilities.
3. InputRequiredResult is allowed ONLY on tools/call, resources/read, and prompts/get. Servers MUST NOT send it on any other client request, and MUST NOT assume the client will fulfill the requests or retry.
4. requestState is opaque to clients: echo it back byte-exact on retry, never inspect, parse, or modify it. Servers MUST treat incoming requestState as attacker-controlled — protect integrity (HMAC or AEAD) whenever it influences authorization, resource access, or business logic, and reject state that fails verification. Embed the authenticated principal, a short TTL, and an identifier of the originating request; enforce single-use server-side where at-most-once matters.
5. The retry is an independent request: it MUST use a different JSON-RPC id, with the client's answers in inputResponses (keys matching inputRequests). If responses are missing, servers SHOULD return a new InputRequiredResult asking again, not an error.
6. Every result now carries a required resultType: "complete" or "input_required". Clients MUST treat results from earlier-protocol servers that omit the field as "complete" — this is the backward-compatibility hinge.

Cacheable lists and notifications

1. tools/list, prompts/list, resources/list, resources/read, and resources/templates/list results MUST carry ttlMs (freshness hint, milliseconds) and cacheScope ("public" or "private" — whether shared intermediaries may cache) via the CacheableResult interface (SEP-2549).
2. Return tools from tools/list in deterministic order — it enables client-side caching and stable upstream LLM prompt-cache hits across reconnects.
3. The HTTP GET endpoint and resources/subscribe/resources/unsubscribe are replaced by subscriptions/listen: one long-lived POST-response stream, opted into per type (toolsListChanged, promptsListChanged, resourcesListChanged, resourceSubscriptions), with notifications tagged io.modelcontextprotocol/subscriptionId. Request-scoped notifications/progress and notifications/message stay on the originating request's response stream.
4. ping, logging/setLevel, and notifications/roots/list_changed are removed. Log level is set per-request via io.modelcontextprotocol/logLevel in _meta; servers MUST NOT emit notifications/message for requests that did not include it.
5. SSE resumability is removed (Last-Event-ID, SSE event IDs). A broken response stream loses the in-flight request — re-issue it as a new request with a new request ID.

Authorization

1. Prefer Client ID Metadata Documents (CIMD): the client_id is an HTTPS URL with a path component (e.g. https://example.com/client.json) serving a JSON document with at least client_id, client_name, redirect_uris; the document's client_id MUST match the URL exactly. Authorization servers advertise support via client_id_metadata_document_supported: true. CIMD client IDs are portable across authorization servers — no re-registration when the AS changes.
2. Registration priority order: (1) pre-registered credentials, (2) CIMD if advertised, (3) Dynamic Client Registration as deprecated fallback, (4) prompt the user.
3. If you must use DCR, set application_type explicitly: "native" for desktop/CLI/localhost apps, "web" for remote browser apps. Omitting it defaults to "web" under OIDC and breaks localhost redirect URIs.
4. Validate the RFC 9207 iss parameter, when present, against the recorded issuer before redeeming any authorization code (SEP-2468). Key persisted credentials by issuer; MUST NOT reuse them with a different authorization server; MUST re-register when the AS changes (SEP-2352).

Extensions and deprecations

1. Negotiate extensions through the new extensions field on ClientCapabilities/ServerCapabilities. Tasks moved from experimental core to the io.modelcontextprotocol/tasks extension: blocking tasks/result → polling tasks/get, new tasks/update for client-to-server input, tasks/list removed, unsolicited task handles allowed (SEP-2663). Other notable extensions: MCP Apps (inline interactive UI), Skills over MCP (rich structured instructions for agent workflows), Enterprise Managed Authorization (EMA).
2. Roots, Sampling, and Logging are Deprecated (SEP-2577) with a minimum twelve-month window. Migrate: Roots → pass directories/files via tool parameters, resource URIs, or server configuration; Sampling → integrate directly with LLM provider APIs; Logging → stderr on stdio, or OpenTelemetry. _meta OTel keys are traceparent, tracestate, baggage.
3. HTTP+SSE transport is formally Deprecated with a year-long offramp — migrate to Streamable HTTP. includeContext values "thisServer"/"allServers" are Deprecated — omit the field or use "none".
4. Error-code updates: resource-not-found moves -32002 → -32602 (Invalid Params); -32020..-32099 is reserved for the MCP spec (HeaderMismatch -32020, MissingRequiredClientCapability -32021, UnsupportedProtocolVersion -32022); -32000..-32019 stays implementation-defined.

Checklist

Server

• [ ] Upgrade to a 2026-07-28-capable SDK (Tier 1: TypeScript, Python, Go, C#; Rust in beta).
• [ ] Delete session/handshake logic; read io.modelcontextprotocol/protocolVersion + clientCapabilities from _meta; return UnsupportedProtocolVersionError (-32022) on mismatch.
• [ ] Implement server/discover.
• [ ] Convert every server-initiated elicitation/create / sampling/createMessage / roots/list into MRTR (InputRequiredResult + integrity-protected requestState); only on tools/call, resources/read, prompts/get.
• [ ] Add resultType to all results; add ttlMs + cacheScope to the five cacheable list/read results; make tools/list order deterministic.
• [ ] Replace GET endpoint and resources/subscribe/unsubscribe with subscriptions/listen; drop ping and logging/setLevel; gate notifications/message on the request's io.modelcontextprotocol/logLevel.
• [ ] Move cross-call state into server-minted handles passed as tool arguments.
• [ ] Schedule removal of any Roots/Sampling/Logging usage within the twelve-month window.

Gateway / proxy / WAF

• [ ] Route, meter, rate-limit, and authorize on Mcp-Method + Mcp-Name; stop parsing JSON bodies for routing.
• [ ] Remove Mcp-Session-Id sticky-session affinity; plain round-robin is now valid.
• [ ] Cache only cacheScope: "public" responses at shared intermediaries, within ttlMs.
• [ ] Support long-lived POST response streams for subscriptions/listen; drop Last-Event-ID replay logic.
• [ ] Pass through Mcp-Param-* custom headers (mirrored from x-mcp-header-annotated tool parameters).

Client

• [ ] Stamp every request: MCP-Protocol-Version + Mcp-Method headers (plus Mcp-Name on tools/call, resources/read, prompts/get); _meta protocolVersion/clientCapabilities/clientInfo.
• [ ] Handle resultType: "input_required": fulfill inputRequests, echo requestState exactly, retry with a NEW JSON-RPC id and inputResponses; treat a missing resultType from older servers as "complete".
• [ ] Declare only capabilities you actually handle — servers may not send undeclared inputRequests types.
• [ ] Cache list results per ttlMs/cacheScope; opt into the subscriptions/listen notification types you need.
• [ ] On broken streams, re-issue the request with a new id — no resumption exists.
• [ ] Auth: host a CIMD document (HTTPS URL client_id, matching client_id field, client_name, redirect_uris); check client_id_metadata_document_supported; fall back to DCR with explicit application_type; validate iss; key credentials by issuer.
• [ ] Do not add Roots/Sampling/Logging support in new code.

Anti-patterns

• Keeping Mcp-Session-Id, sticky sessions, or the initialize handshake — the transport no longer defines them.
• Sending server-initiated elicitation/create, sampling/createMessage, or roots/list requests — no longer supported at all.
• Inspecting, parsing, or mutating requestState on the client; accepting it on the server without integrity verification when it affects authorization or business logic.
• Reusing the same JSON-RPC id on an MRTR retry — initial request and retry are independent requests.
• Relying on Last-Event-ID / SSE event-ID redelivery after a dropped stream.
• Emitting notifications/message for requests that did not set io.modelcontextprotocol/logLevel.
• Varying list results per connection or returning tools in nondeterministic order — breaks client caches and prompt caching.
• New implementations adopting Roots, Sampling, Logging, DCR, HTTP+SSE, or includeContext: "thisServer"/"allServers" — all Deprecated.
• Reusing OAuth client credentials across different authorization servers instead of re-registering keyed by issuer.

Source

• MCP Specification 2026-07-28 (incl. changelog, MRTR pattern, client registration) — https://modelcontextprotocol.io/specification/2026-07-28 — 2026-07-28
• The 2026-07-28 Specification (maintainers deep-dive) — https://blog.modelcontextprotocol.io/posts/2026-07-28/ — 2026-07-28

Distilled from the official document(s) above on 2026-08-12. If this skill and the source disagree, trust the source.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Archive228
• Source: Archive228/lab-skills
• License: MIT

Install and usage instructions live in the source repository linked above.