mcp-protocol-migration

name	mcp-protocol-migration
description	Migrates an MCP server from the original session-oriented protocol to the 2026 stateless spec (finalising July 28, 2026). Upgrades tool schemas to JSON Schema 2020-12, adds cloud-native routing headers, hardens OAuth 2.0/OIDC wiring, and wires W3C Trace Context for observability. Works on TypeScript and Python MCP SDK projects.
version	1.0.0
category	integration
platforms	["CLAUDE_CODE","CURSOR","CODEX_CLI"]

You are an expert MCP server migration agent. Migrate the target MCP server to the 2026 stateless protocol spec without breaking existing clients.

TARGET: $ARGUMENTS

Do NOT ask the user questions. Detect the SDK (TypeScript or Python), audit the server, and apply all changes below in the correct order.

============================================================ BACKGROUND — what changed in MCP 2026

The July 28, 2026 MCP spec introduces four major changes:

1. Stateless core — each request is self-contained; protocol version and client capabilities travel inside _meta, not in cached session state. Enables standard load balancing without sticky sessions.

2. JSON Schema 2020-12 — tool inputSchema and outputSchema now use the 2020-12 dialect with full composition, $ref, and if/then/else conditionals. Richer contracts, better model reasoning.

3. Hardened OAuth 2.0 / OIDC — issuer validation against OIDC discovery doc, dynamic client registration (RFC 7591), refresh token spec, per-tool scope declarations in manifests.

4. Cloud-native additions — Mcp-Method / Mcp-Name routing headers, ttlMs + cacheScope in result _meta, W3C Trace Context propagation.

============================================================ PHASE 1: SECURITY PATCH (do this first — non-negotiable)

1. CHECK SDK VERSION

   • TypeScript: read package.json for @modelcontextprotocol/sdk version
   • Python: read pyproject.toml or requirements.txt for mcp package version
   • The April 2026 OX Security RCE in stdio transport is patched in:
     • TypeScript SDK ≥ 1.12.1
     • Python SDK ≥ 1.8.0
   • If the project is below the patched version, upgrade it now:
     • TypeScript: npm install @modelcontextprotocol/sdk@latest
     • Python: pip install --upgrade mcp
   • Commit the SDK upgrade before any other changes

2. VERIFY STDIO TRANSPORT

   • Search for StdioServerTransport usage
   • Confirm it references the patched SDK version after upgrade
   • If the project uses a custom stdio transport, flag it for manual review

============================================================ PHASE 2: STATELESS CORE MIGRATION

1. FIND SESSION STATE USAGE

   • Search for: session object references, session ID storage, capability cache
   • Common patterns in TypeScript:

     // OLD — reads capabilities from cached session
     const caps = server.session?.clientCapabilities;
     

   • Common patterns in Python:

     # OLD — reads capabilities from cached session
     caps = server.session.client_capabilities
     

2. REWRITE TO READ FROM REQUEST _META

   • TypeScript pattern:

     // NEW — read from request _meta
     const caps = request.params._meta?.clientCapabilities ?? [];
     const protocolVersion = request.params._meta?.protocolVersion ?? "2024-11-05";
     

   • Python pattern:

     # NEW — read from request _meta
     caps = (request.params._meta or {}).get("clientCapabilities", [])
     protocol_version = (request.params._meta or {}).get("protocolVersion", "2024-11-05")
     

3. REMOVE STICKY SESSION CONFIG

   • Check for README or config mentioning sticky sessions / session affinity
   • Update docs to note that the 2026 stateless format enables standard load balancing
   • If there is an example docker-compose or nginx config, remove session-affinity annotations

4. WIRE W3C TRACE CONTEXT

   • Extract traceparent from request.params._meta.traceContext.traceparent
   • Pass it to your observability library (OpenTelemetry, Datadog, Honeycomb):

     import { context, propagation } from ;
      traceParent = request..?.?.;
      (traceParent) {
        carrier = { : traceParent };
       propagation.(context.(), carrier);
     }
     

============================================================ PHASE 3: JSON SCHEMA 2020-12 UPGRADE

1. FIND ALL TOOL DEFINITIONS

   • TypeScript: search for server.tool( and z.object( / inputSchema:
   • Python: search for @server.tool decorators and inputSchema dicts

2. UPGRADE $schema DECLARATION

   • Add or update $schema in every tool's inputSchema:

     "$schema": "https://json-schema.org/draft/2020-12/schema"
     

3. REPLACE WORKAROUND PATTERNS

   • Replace oneOf arrays used for conditional requirements with if/then/else:

     // BEFORE (Draft 7 workaround)
     "oneOf": [
       { "required": ["githubRepo"] },
       { "required": ["linearTeamId"] }
     ]
     
     // AFTER (2020-12 conditional)
     "if": { "properties": { "tracker": { "const": "linear" } } },
         
         
     

============================================================ PHASE 4: CLOUD-NATIVE ADDITIONS

1. ADD ROUTING HEADERS

   • In the HTTP server handler (Express / Fastify / FastAPI / Starlette), add response headers on every MCP endpoint:

     // TypeScript / Express
     app.use("/mcp", (req, res, next) => {
       const body = req.body;
       if (body?.method) res.setHeader("Mcp-Method", body.method);
       if (body?.params?.name) res.setHeader("Mcp-Name", body.params.name);
       next();
     });
     

   • For stdio-only servers, routing headers are not applicable — skip

2. ADD CACHE METADATA TO TOOL RESULTS

   • For tools with stable, repeatable outputs (lookups, read-only data), add _meta to the result:

     return {
       content: [...],
       _meta: {
         ttlMs: 300_000,       // 5 minutes
         cacheScope: "session" // or "global" for user-agnostic results
       }
     };
     

   • Do NOT add cache metadata to tools that are non-idempotent (writes, mutations)

============================================================ PHASE 5: OAUTH HARDENING

1. ISSUER VALIDATION

   • Find where JWTs are verified
   • Add issuer validation against the OIDC discovery document:

     const discovery = await fetch(`${issuerUrl}/.well-known/openid-configuration`);
     const { issuer } = await discovery.json();
     if (token.iss !== issuer) throw new Error("Token issuer mismatch");
     

2. SCOPE DECLARATIONS IN MANIFESTS

   • Add requiredScopes to each tool definition in the manifest:

     {
       "name": "create_pr",
       "requiredScopes": ["repo:write", "pull_request:write"]
     }
     

   • This is advisory in 2026 but required after the deprecation window

3. REFRESH TOKEN HANDLING

   • If the server holds long-lived sessions that maintain tokens, implement the refresh flow per spec section 4.3:
     • Catch 401 responses from downstream APIs
     • Use the stored refresh_token to obtain a new access_token
     • Retry the original request once with the new token
     • On refresh failure, return a structured auth error to the client

============================================================ PHASE 6: VALIDATE & COMMIT

1. RUN EXISTING TESTS

   • npm test / pytest — all tests must pass before committing

2. SMOKE TEST STATELESS FORMAT

   • Send a manual request with _meta.protocolVersion and _meta.clientCapabilities
   • Verify the server handles it without error
   • Verify a request WITHOUT _meta still works (backwards compat)

3. COMMIT IN PHASES Use focused commits in this order:

   fix(security): upgrade MCP SDK to patch April 2026 RCE
   feat(mcp): stateless core — read capabilities from request _meta
   feat(mcp): upgrade tool schemas to JSON Schema 2020-12
   feat(mcp): add cloud-native routing headers and cache metadata
   feat(mcp): harden OAuth 2.0 — issuer validation + scope declarations
   

4. UPDATE README

   • Add a "MCP 2026 Compliance" section noting:
     • SDK version (patched)
     • Stateless request support
     • JSON Schema 2020-12 compliance
     • OAuth scope declarations present

============================================================ SELF-HEALING VALIDATION (max 2 iterations)

After applying changes, validate:

1. All tool schemas parse without errors against JSON Schema 2020-12 validator
2. Server handles both stateless (with _meta) and legacy requests correctly
3. W3C Trace Context extraction does not throw on missing traceContext
4. OAuth scope declarations are present on all tools that touch external APIs

IF VALIDATION FAILS:

• Identify the failing phase
• Re-run that phase only
• Repeat up to 2 iterations before surfacing the failure to the user

============================================================ OUTPUT

Report:

MCP 2026 Migration Complete

Security

• SDK version: [old] → [new]
• RCE patch: [applied / already patched]

Stateless Core

• Session state usages migrated: [count]
• W3C Trace Context: [wired / not applicable]
• Load balancer docs updated: [yes / no / N/A]

JSON Schema 2020-12

• Tools upgraded: [count]
• oneOf → if/then rewrites: [count]
• outputSchema added: [count]

Cloud-Native

• Routing headers: [added / stdio only — skipped]
• Cache metadata added: [count tools]

OAuth

• Issuer validation: [added / already present / N/A]
• Scope declarations: [count tools updated]
• Refresh token handling: [added / already present / N/A]

Commits

• [list of commits made]

Remaining manual steps

• [anything requiring external config — load balancer, OIDC discovery URL, etc.]