| name | mcp-2026-migration |
| description | Use when a server or client must move from MCP 2025-11-25 or earlier to 2026-07-28, when initialize or session IDs fail, or when modern HTTP requests return -32020, -32021, or -32022. |
| version | 0.1.0 |
Migrate MCP to 2026-07-28
Diagnose first. Capture the endpoint, exact request/response body, relevant headers with secrets redacted, SDK version, and whether the peer is modern, legacy, or dual-era.
Operating rules
- Never add a
sessionIdGenerator or session map to hide a modern failure.
- Never fall back to
initialize merely because a modern probe returned HTTP 400. Inspect the JSON-RPC error first.
- Never treat
requestState as trusted data.
- Keep an intentional dual-era path explicit; do not call an accidental legacy fallback compatibility.
Removals and replacements
| Removed modern mechanism | Replacement |
|---|
initialize / notifications/initialized | Per-request _meta; optional server/discover |
Mcp-Session-Id | Explicit application handle in tool arguments |
| Server-initiated elicitation/sampling/roots | MRTR input_required result and client reissue |
notifications/elicitation/complete, elicitationId | inputResponses keyed by server-assigned names |
ping, logging/setLevel | Ordinary health endpoint; per-request log-level metadata |
| Resource subscribe/unsubscribe and HTTP GET stream | subscriptions/listen |
Roots, Sampling, Logging, and DCR are deprecated, not new-design defaults. Do not emit reserved -32002 or -32042.
Per-request contract
Every modern request contains _meta.io.modelcontextprotocol/protocolVersion and _meta.io.modelcontextprotocol/clientCapabilities; include clientInfo unless intentionally disabled. Every HTTP POST carries MCP-Protocol-Version matching the body, and every HTTP request carries Mcp-Method. tools/call, resources/read, and prompts/get additionally require Mcp-Name.
Use Mcp-Param-{Name} only for valid x-mcp-header inputs. The body wins; any mismatch is rejected.
| Error | Meaning | First check |
|---|
-32020 | Header mismatch | Header spelling, value encoding, _meta/header version equality |
-32021 | Missing required client capability | This request's _meta.clientCapabilities, not an earlier call |
-32022 | Unsupported protocol version | Server's supported list and the request's declared version |
MRTR
A handler returns resultType: "input_required", inputRequests, and/or sealed requestState. The client obtains input and reissues the original request using a new JSON-RPC ID with inputResponses. Only tools, prompts, and resources may use this result shape. A task-managed operation instead follows its extension's tasks/update flow.
Failure map
| Symptom | Likely cause | Correct next action |
|---|
initialize gets 404/405 | Endpoint is modern-only | Probe server/discover; migrate client or use a deliberate dual-era endpoint |
Tool absent from tools/list | Invalid x-mcp-header declaration | Keep header-marked input primitive and statically reachable under root properties |
HTTP 400 with -32020/-32021/-32022 | Modern server rejected a modern request | Fix the named modern contract violation; do not fall back |
| Empty/unstructured HTTP 400 to discover | Possible legacy endpoint | Try legacy initialize, then cache the established era |
| Modern GET/DELETE gets 405 | Correct stateless behavior | Use POST per-request calls; do not resume/delete a session |
Run scripts/mcp_2026_probe.py before changing code. It performs an evidence-only modern probe, only falls back when the result is not modern evidence, and redacts authorization-like header values.
References
references/versions.md — protocol ledger and verification commandsscripts/mcp_2026_probe.py — dual-era evidence probe
