Migrating an HTTP MCP server to 2026-07-28 while serving older clients

Goal

Status as of 25 October 2026. Migrate an HTTP MCP server to revision 2026-07-28 while preserving an explicitly supported 2025-11-25 client path. Re-check the versioned transport, message schemas and chosen SDK's documented support before deployment. This is a proposed acceptance procedure, not a report of a tested migration.

Prerequisites

Inventory client protocol revisions, initialization handlers, session storage, callbacks, subscriptions and authorization policies. Prepare a staging endpoint behind the production-style gateway, a rollback configuration, and clients for both revisions. Use harmless test tools and separate test identities. Record the actual SDK package version; a protocol revision is not a package version.

Steps

1. Separate protocol paths. The compatibility rules permit both behaviors on one endpoint. A legacy initialize selects legacy semantics; modern per-request metadata selects stateless processing. Preserve the older revision's negotiated behavior while its clients remain supported. Do not apply modern header requirements indiscriminately to legacy initialization.

2. Make requests self-contained. Require io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities in params._meta. Include client identity as recommended, but never use this self-reported identity as authorization. Stop deriving capabilities or application context from the previous connection. Expose explicit identifiers for state spanning calls.

3. Implement discovery and transport validation. Implement server/discover, mirror the version into MCP-Protocol-Version, and validate required headers against the body. A discovery smoke check for a staging endpoint without authentication is:

   curl --request POST 'https://mcp.example.com/mcp' \
     --header 'Content-Type: application/json' \
     --header 'Accept: application/json, text/event-stream' \
     --header 'MCP-Protocol-Version: 2026-07-28' \
     --header 'Mcp-Method: server/discover' \
     --data '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{},"io.modelcontextprotocol/clientInfo":{"name":"migration-check","version":"local"}}}}'
   

   Replace the example URL. For protected endpoints, use the deployment's approved authenticated test client; do not disable authentication to run this check.

4. Update results and interactions. Emit resultType: "complete" for ordinary results. Implement MRTR for permitted interactive operations: return input_required, then accept matching inputResponses and the unchanged opaque requestState on a new request ID. Verify state integrity when it affects permissions or business logic; bind it to the principal, expiry and originating operation as recommended. Enforce one-time consumption server-side where required.

5. Migrate notifications and caching. Replace the standalone GET notification stream with subscriptions/listen. Preserve request-scoped SSE where used, but remove Last-Event-ID resumption: closing a response stream signals cancellation. Add nonnegative ttlMs and the appropriate cacheScope to complete results covered by the caching specification. Exclude interim and MRTR-retry results from caching.

6. Test version recovery deliberately. An unsupported modern version returns UnsupportedProtocolVersionError with supported versions. Clients should retry a compatible version. On HTTP 400, inspect the JSON-RPC body: recognized modern errors require correction or version selection; an empty or unrecognized body permits legacy initialization fallback. Do not downgrade merely because a valid modern request was rejected.

7. Exercise the deployment boundary. In staging, run discovery, list retrieval, a harmless call, an interactive retry and a subscription through the gateway. Repeat with a legacy client and route modern requests across instances. Interrupt a harmless SSE response and verify cancellation and safe recovery without resumption. Verify authorization for each identity and confirm that request metadata reaches the server unchanged.

Expected result

Both supported revisions complete their own workflows. Modern operations require no transport session; legacy clients retain their negotiated lifecycle. Keep the old configuration available until the acceptance checks pass.

Limits and test basis

The cited specification defines protocol behavior; the steps above are an operator's proposed verification plan. They do not establish SDK compatibility, retry safety for business actions, or successful operation on any particular load balancer. Those require deployment-specific tests.