2026-07-28 readiness: peer SDK is being retired, plus 405 / CORS / HeaderMismatch gaps

[quotentiroler]

Filing this as an issue rather than a PR because the obvious one-line change does not exist, and the real change needs a maintainer decision.

The peer dependency cannot just be bumped

The plan was "bump @modelcontextprotocol/sdk from >=1.29.0 to a beta that supports 2026-07-28." That is not possible. Verified against npm today:

$ npm view @modelcontextprotocol/sdk dist-tags --json
{ "latest": "1.29.0" }                 # no beta / next / rc tag
                                       # only prerelease ever published: 1.23.0-beta.0

$ npm view @modelcontextprotocol/server dist-tags --json
{ "latest": "2.0.0-beta.5", "beta": "2.0.0-beta.5" }

$ npm view @modelcontextprotocol/client dist-tags --json
{ "latest": "2.0.0-beta.5", "beta": "2.0.0-beta.5" }

Per the SDK beta announcement: "TypeScript v2 retires the monolithic @modelcontextprotocol/sdk package in favor of focused ones, like @modelcontextprotocol/server for servers, @modelcontextprotocol/client for clients."

So this is a peer swap, not a version bump, and it touches our public contract plus every import path:

• peerDependencies: @modelcontextprotocol/sdk -> @modelcontextprotocol/server
• src/transport.ts: @modelcontextprotocol/sdk/server/webStandardStreamableHttp.js, @modelcontextprotocol/sdk/server/mcp.js
• consumers' McpServer import, i.e. every example in the README

Decision needed before any code: do we (a) cut 0.2.x on the v2 beta and leave 0.1.x on the 1.x line, (b) support both generations behind separate entry points (/v2?) with both peers optional, or (c) wait for @modelcontextprotocol/server to go stable? My read is (a), since straddling two SDK generations in one transport is how this package stops being small, but it is your call and it is breaking either way.

Transport-layer gaps, independent of the SDK

These are ours regardless of which SDK we peer on, since they are HTTP behaviour rather than protocol semantics.

1. HeaderMismatch validation is unimplemented. Spec:

Servers that process the request body MUST reject requests where the values specified in the headers do not match the corresponding values in the request body. [...] servers MUST return HTTP status 400 Bad Request and MUST include a JSON-RPC error response using [...] -32020 HeaderMismatch.

Failure conditions include a missing required header (MCP-Protocol-Version, Mcp-Method, Mcp-Name), a header that does not match the body, and invalid characters. Note Mcp-Name is required only for tools/call, resources/read and prompts/get, and its value may arrive Base64-wrapped as =?base64?...?=, which we must decode before comparing. -32020 should join JSON_RPC_ERROR_CODES in src/errors.ts.

2. GET / DELETE should be 405, not 404. The spec says a server on this revision receiving legacy traffic SHOULD respond:

HTTP GET or DELETE to the MCP endpoint: respond with 405 Method Not Allowed.

Our documented lifecycle 404s everything that is not a POST or a well-known path. This matters for real interop: clients use 400 / 404 / 405 plus the body shape to decide whether to fall back to the legacy initialize era, so a 404 here is actively misleading.

3. Default CORS exposes two headers that no longer exist. exposeHeaders defaults include Mcp-Session-Id and Last-Event-ID. Sessions are gone (SEP-2567) and Last-Event-ID resumability is gone ("Resumable SSE streams via Last-Event-ID are not supported"). Harmless but wrong, and it should not be trimmed until we decide the story for handleMcpPostStateful below.

4. handleMcpPostStateful is now a legacy-only path. It routes on Mcp-Session-Id and mints sessions on initialize (src/transport.ts), both removed in this revision. Its reason to exist was server-initiated RPC, which SEP-2322 replaces with InputRequiredResult embedded in results, and the spec is explicit that a server "MUST NOT send independent JSON-RPC requests" on a response stream. Sampling / roots / logging are deprecated on a twelve-month clock, and ping / logging/setLevel / notifications/roots/list_changed are removed now. Suggest we document it as legacy-clients-only and stop presenting it as the sampling escape hatch.

5. subscriptions/listen is the new push mechanism. The standalone GET stream is gone; long-lived change notifications now ride the response stream of a subscriptions/listen POST. Mostly SDK territory, but we should confirm our SSE cleanup in handleMcpPost does not close the server on a stream that is meant to stay open. The current code defers server.close() until the stream completes, which looks right, though a keep-alive comment line (:\r\n) is encouraged for quiet periods and we do not emit one.

The good news

The core shape needs no redesign, which was the whole bet. handleMcpPost already constructs one WebStandardStreamableHTTPServerTransport per POST with no sessionIdGenerator, and createServer(token, ctx) is already a per-request factory. Nothing above touches consumers' tools.

Suggested sequencing

1. Land 405 + -32020 validation + an errors.ts code, all additive and testable against 1.x today.
2. Decide the SDK strategy above, then do the peer swap and import rewrite as its own breaking release.
3. Trim CORS defaults and re-document handleMcpPostStateful in that same breaking release.

Happy to open (1) as a PR now, since it is unblocked. (2) needs your answer first.

[quotentiroler]

Updating the npm findings in the opening post, which have since gone stale.

Verified on npm today (2026-07-31):

package	in this issue (2026-07-25)	now
@modelcontextprotocol/sdk	1.29.0, no beta tag	1.30.0
@modelcontextprotocol/server	2.0.0-beta.5	2.0.0
@modelcontextprotocol/client	2.0.0-beta.5	2.0.0
@modelcontextprotocol/hono	2.0.0-beta.5	2.0.0
@modelcontextprotocol/node	2.0.0-beta.5	2.0.0
@modelcontextprotocol/express	2.0.0-beta.5	2.0.0

v2 2.0.0 was published 2026-07-27T23:55Z. So option (c), wait for @modelcontextprotocol/server to go stable, is resolved and no longer a reason to defer the decision. That decision is tracked in #8, where I have posted the same table.

On the sequencing proposed here:

• Step 1 is partly done. The 405 for GET / DELETE described in item 2 was already correct in handler.ts; it is the request-lifecycle diagram in the README that showed a catch-all 404. What was actually broken is now fixed on develop (CORS: browser clients fail preflight on MCP-Protocol-Version #7): Access-Control-Allow-Methods was hardcoded to GET, POST, DELETE, OPTIONS and contradicted that 405, and MCP-Protocol-Version was missing from Access-Control-Allow-Headers. Both now derive from a shared route table in src/routes.ts, with a test asserting the preflight value and the 405 Allow header agree.
• -32020 HeaderMismatch from item 1 is still open and still unblocked.
• Item 3, trimming Mcp-Session-Id and Last-Event-ID from the CORS defaults, is untouched on purpose, since it is gated on the handleMcpPostStateful decision in Migrate to stateless MCP (2026-07-28): prune the session-based transport path #5.

We are also on @modelcontextprotocol/sdk@1.30.0 as of the latest dependency bump on develop.

[quotentiroler]

Two items here are already resolved.

The 405 gap was fixed: handler.ts returns 405 with an Allow header derived from routes.ts, and preflight advertises the same set, so the description of a catch-all 404 is out of date.

The CORS allow-list is fixed in dfd6f1a, which adds Mcp-Method and Mcp-Name. They are request headers, so the original suggestion to put them in Access-Control-Expose-Headers was the wrong list.

Mcp-Session-Id and Last-Event-ID stay in the allow list for now because we still drive the sessionful transport. They go when #5 does.

The -32020 item should move under #8. Verified against the installed SDK: the validation ladder exists only on the createMcpHandler path, and it is substantial (inbound ladder, base64 sender-encoding, numeric canonicalisation, per-tool SEP-2243 Mcp-Param-* checks). We get it by delegating rather than by writing it here.

[quotentiroler]

Closing: all four items are resolved, though not all in the way this issue proposed.

1. HeaderMismatch / -32020 — resolved in 0.4.0, by delegating rather than implementing. The inbound validation ladder that emits it lives only on the createMcpHandler path, and it covers considerably more than the header/body cross-check described here: SEP-2243 Mcp-Param-* validation against each tool's x-mcp-header declarations, base64 sentinel decoding, and numeric canonicalisation. Reimplementing that locally would have been a large duplicate of a subtle subsystem. Covered by test/protocol-2026-07-28.test.ts.

2. GET/DELETE should be 405 — was already fixed when this issue was filed. handler.ts returns 405 with an Allow header derived from routes.ts, and preflight advertises the same set, so the description of a catch-all 404 was out of date.

3. CORS defaults — resolved across 0.3.2 and 0.4.1, with a correction to the proposal. Mcp-Method and Mcp-Name were missing and were added in 0.3.2; they are request headers, so the suggestion to put them in Access-Control-Expose-Headers was the wrong list.

Mcp-Session-Id and Last-Event-ID were removed in 0.4.0 and put back in 0.4.1. The spec's backward-compatibility section says a server receiving 2025-era traffic should ignore them, not refuse them, and omitting a header from the allow-list fails preflight, so a browser-hosted legacy client could never send the request. Only Mcp-Session-Id left the exposed headers, which is correct now that sessions are gone.

4. handleMcpPostStateful as a legacy-only path — overtaken. It was removed outright in 0.4.0 (#5). Legacy clients are still served, statelessly, via createMcpHandler's legacy: 'stateless' default.

5. subscriptions/listen keep-alive — the SDK emits X-Accel-Buffering: no and owns the SSE keep-alive, so the concern about our cleanup closing a long-lived stream no longer applies to code here.

On the peer dependency: the swap to @modelcontextprotocol/server landed in 0.3.0, and v2 went stable, so option (c) "wait for stable" is moot. The re-layer that 0.3.0 did not do was completed in 0.4.0.

Shipped across 0.3.2, 0.4.0 and 0.4.1.