Uh oh!
There was an error while loading. Please reload this page.
[SEP-2575][SEP-2322][SEP-2567] 2026-06 stateless support over StreamableHTTP - #2131
[SEP-2575][SEP-2322][SEP-2567] 2026-06 stateless support over StreamableHTTP#2131felixweinberger wants to merge 10 commits into
Conversation
🦋 Changeset detectedLatest commit: ddfc2b3 The changes in this PR will be included in the next version bump. This PR includes changesets to release 7 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
@modelcontextprotocol/client@modelcontextprotocol/server@modelcontextprotocol/express@modelcontextprotocol/fastify@modelcontextprotocol/hono@modelcontextprotocol/nodecommit: |
dd9e762 to
af76de4Compare5b5c538 to
09fc142Comparedd9e762 to
af76de4Comparefelixweinberger
commented
May 21, 2026
@claude review |
09fc142 to
315684dCompareaf76de4 to
b837b6cCompareUh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
NEW core/shared/stateless.ts: parseClientMeta, ClientMeta, META_KEYS, STATEFUL_PROTOCOL_VERSIONS, isStatelessProtocolVersion, isStatelessRequest, STATELESS_REMOVED_METHODS, InputRequiredError/isInputRequiredError, DispatchContext, StatelessHandlers, ListenContext, ListenStream. Transport interface gains optional setStatelessHandlers (server-side) and sendAndReceive (client-side). Both unimplemented at this commit; transport routers and Client wiring come in P3. Exported from core internal barrel and core/public. Satisfies: 2575-R1 (per-request _meta keys), 2575-R3 (version classification)
`subscriptions/listen` is the one 2026-06 method that is request->stream rather than request->response, so it lives outside the dispatcher. InMemorySubscriptions: in-memory backend keyed by server-minted UUID (clients on a shared instance cannot collide); wire `_meta.subscriptionId` is `String(request.id)`. Queue cap 256 (evict slow consumers). `resourceSubscriptions` capped at 256 + Set lookup; fail-closed without `onAuthorizeResourceSubscription`. Satisfies: 2575-R6 (subscriptions/listen + ack)
…iptions + statelessHandlers (sectioned)
Server (existing class, extends Protocol) gains a clearly-divided
`// 2026 stateless` section with:
- `subscriptions: SubscriptionBackend` (defaults to InMemorySubscriptions)
- `statelessHandlers(): {dispatch, listen}`
- `_dispatchStateless(req, dctx)` — version check, removed-methods reject,
build ctx, dispatcher.dispatch, default resultType (not for discover)
- `_buildDispatchServerContext` — MRTR throw-then-cache for elicit/sampling/
listRoots, notify stamps subscriptionId (server wins), log severity-gated,
send throws
- `_ondiscover()` — returns supportedVersions/capabilities/serverInfo
- `inputRequiredMiddleware` (module-level) — InputRequiredError → cap-gate
→ InputRequiredResult
`// dual-mode` section: `connect()` override wires setStatelessHandlers;
`send*ListChanged` get `subscriptions.notify(...)` prepended.
`ServerContext` gains `clientCapabilities?` + `mcpReq.listRoots`. Existing
`buildContext` populates them from session state.
Existing session-dependent methods (`createMessage`, `elicitInput`,
`listRoots`, `sendLoggingMessage`, `_oninitialize`, `ping`, etc.) are
unchanged; comment divider documents the per-method 2026 equivalents.
`ProtocolErrorCode.MissingRequiredClientCapability = -32003` added (spec
`MISSING_REQUIRED_CLIENT_CAPABILITY`).
Satisfies: 2575-R2 (discover), 2575-R4 (removed methods), 2575-R5 (per-request
ctx), 2322-R1 (InputRequiredError), 2322-R2 (cap-gate -32003)Tool wrapper catch checks isInputRequiredError(e) and re-throws so inputRequiredMiddleware translates to InputRequiredResult (otherwise the error would be swallowed into an isError:true CallToolResult and MRTR would not work for McpServer-registered tools). McpServer.sendLoggingMessage JSDoc points to ctx.mcpReq.log() for the both-protocols path. Satisfies: 2322-R2
`statelessHttpHandler(handlers, req, opts)`: POST-only, CT exact-match → 415, bounded streaming reader (never trust Content-Length), batch cap 64, per-request `_meta` validation (presence, stateless-ness, header agreement), `subscriptions/listen` → SSE, dispatch → JSON or SSE per Accept. Explicit 400 for non-request/non-notification messages. `sseResponse` releases listener registration in `finally` (not only via abort). `handleHttp(server, opts)`: host/origin allowlist BEFORE auth callback, IPv6-safe `stripPort` (brackets removed), then `statelessHttpHandler`. `SUPPORTED_PROTOCOL_VERSIONS` gains `DRAFT_PROTOCOL_VERSION` (at the end so `[0]` stays latest-released; 2026 is opted into via discover auto-probe). `ProtocolErrorCode.HeaderMismatch = -32001`. Satisfies: 2575-R7 (HTTP entry), 2575-R8 (per-request _meta validation), 2567-R1 (header/meta agreement)
StreamableHTTPClientTransport.sendAndReceive: async generator over fetch (SSE-parse or JSON body). Auth via _commonHeaders; 401/403 retry left to caller. Self-contained; does not go through Protocol.request(). Satisfies: 2575-R12 (client sendAndReceive contract, HTTP)
streamableHttp server: handleRequest routes by MCP-Protocol-Version header (falls back to body _meta) to statelessHttpHandler; pre-2026 or absent header falls through to handleStatefulRequest (body unchanged, GHSA-345p guard stays inside). Node middleware: setStatelessHandlers forwards to wrapped web-standard transport. Server.connect() already calls transport.setStatelessHandlers?.() (C7). StreamableHTTPClientTransport.sendAndReceive gains opts?.signal (AbortSignal.any with transport-wide controller). Satisfies: 2567-R1 (HTTP), 2575-R7
…ss/subscribe; typed methods route via _send (sectioned) Client (existing class, extends Protocol) gains a `// 2026 stateless` section: - `_isStateless`, `_logLevel` - `_buildMeta()` / `_withMeta()` — namespaced `_meta` from client identity - `_collect(it, opts)` — drain sendAndReceive: progress→onprogress by token, return raw result, throw on JSON-RPC error - `_send(req, schema, opts)` — route via sendAndReceive when stateless, else fall back to `Protocol.request()`. MRTR loop ≤16: on input_required, dispatch each input request via `this.dispatcher.dispatch` (so `_validationMiddleware` runs), accumulate inputResponses + thread requestState, propagate signal - `_negotiate(transport)` — probe server/discover, set `_isStateless` on success, fall through on isFallbackable error (wired to connect() in C13) - `subscribe(filter)` — async generator over subscriptions/listen - `_listChangedLoop` — stateless backing for options.listChanged with debounce `// dual-mode`: typed methods (callTool/listTools/getPrompt/listPrompts/ readResource/listResources/listResourceTemplates/complete) route via `_send`. `setLoggingLevel` stores level for `_buildMeta`, sends legacy RPC when not stateless. `// session-dependent` divider above existing `connect()`/`ping()`/ `subscribeResource()`/`_setupListChangedHandler*` (bodies unchanged). `applyElicitationDefaults` unchanged. Satisfies: 2575-R10 (per-request _meta), 2575-R11 (discover probe), 2575-R12 (sendAndReceive routing), 2322-R3 (MRTR resume loop), 2322-R4 (requestState round-trip)
connect() now probes server/discover via transport.sendAndReceive before the legacy initialize handshake. On success the client enters stateless mode (server identity/capabilities from DiscoverResult, initialize skipped). On MethodNotFound / HTTP 4xx / parse failure it falls through to the legacy initialize (extracted verbatim into _initialize()). _setupListChanged() routes options.listChanged to _listChangedLoop (subscriptions/listen) when stateless, else to the existing notification-handler path. Existing tests that exercise pre-2026 connection-model behavior now need LegacyTestClient (C14).
…atchV2 target NEW test/integration/__fixtures__/testClient.ts: LegacyTestClient — advertises only pre-2026 versions so connect() skips discover probe. NEW statelessAcceptance.test.ts (HTTP scenarios): Server stateless dispatch, SubscriptionBackend, handleHttp, StreamableHTTP zero-change consumer, audit invariants. conformance: extract everythingServerSetup.ts; add everythingServerDispatchV2.ts target wired to run-server-conformance.sh.
315684d to
628f0e1Compareb837b6c to
ddfc2b3Comparefelixweinberger
commented
May 21, 2026
@claude review |
| try { | ||
| for await (const n of this.subscribe(filter, { signal })) { | ||
| debounced[n.method]?.(); | ||
| } | ||
| // Stream ended without error and without our abort: surface so the | ||
| // caller knows list-changed delivery has stopped. | ||
| if (!signal.aborted) { | ||
| throw new SdkError(SdkErrorCode.ConnectionClosed, 'subscriptions/listen stream ended'); | ||
| } | ||
| } finally { | ||
| for (const t of timers.values()) clearTimeout(t); | ||
| timers.clear(); | ||
| } | ||
| } |
There was a problem hiding this comment.
🔴 When close() calls _listChangedAbort?.abort(), the abort propagates into sendAndReceive's reader.read() which rejects with an AbortError; the for await in _listChangedLoop then throws rather than ending, so the post-loop if (!signal.aborted) guard is dead code on the abort path and the rejection lands in _setupListChanged()'s .catch, firing onerror (or console.error) with a spurious AbortError on every clean close() of a stateless client with listChanged configured. Wrap the for await in a try/catch and swallow the error when signal.aborted is true.
Extended reasoning...
What happens
Client.close() does:
overrideasyncclose(): Promise<void>{this._isStateless=false;this._listChangedAbort?.abort();// <-- aborts the listen stream
...
}That signal is passed through _listChangedLoop() → subscribe() → StreamableHTTPClientTransport.sendAndReceive(), where it is composed into the fetch signal (via AbortSignal.any). When the abort fires while the SSE body is being read, reader.read() rejects with an AbortError per the Fetch spec.
Why it surfaces as an error
The rejection then propagates upward through three frames, none of which catch it:
sendAndReceive()'s SSE loop has only atry/finally(thefinallycallsreader.cancel()), so the async generator rethrows.subscribe()'sfor await (const m of sar(...))has notry/catch, so the generator rethrows._listChangedLoop()'sfor await (const n of this.subscribe(...))has only atry/finally(thefinallyclears debounce timers), so the loop rethrows.
The rejection therefore reaches the call site in _setupListChanged():
this._listChangedLoop(kinds).catch(error=>(this.onerror??console.error)(errorinstanceofError ? error : newError(String(error))));which fires the caller's onerror (or dumps to console.error) with the AbortError — on every clean close().
Why this is unintended
The post-loop guard makes the author's intent explicit:
forawait(constnofthis.subscribe(filter,{ signal })){debounced[n.method]?.();}// Stream ended without error and without our abort: surface so the// caller knows list-changed delivery has stopped.if(!signal.aborted){thrownewSdkError(SdkErrorCode.ConnectionClosed,'subscriptions/listen stream ended');}The if (!signal.aborted) check (and its comment) only makes sense if the abort path falls through to that line — i.e. if the loop ends on abort rather than throws. Because it throws, this check is unreachable on the abort path: it is dead code.
Step-by-step proof
new Client(info, { listChanged: { tools: { onChanged } } }).client.connect(streamableHttpTransport)→server/discoversucceeds →_isStateless = true→_setupListChanged()calls_listChangedLoop(kinds)(fire-and-forget with a.catch)._listChangedLoop()creates_listChangedAbort, callssubscribe(filter, { signal }), the SSEsubscriptions/listenstream connects and the loop blocks inreader.read().- Caller does
await client.close(). close()calls_listChangedAbort.abort()→ fetch signal aborts →reader.read()rejects withAbortError→ propagates through all three frames →.catchin_setupListChanged()calls(this.onerror ?? console.error)(AbortError).
The user observes an error on a normal shutdown with no actual problem.
Impact
Not a correctness/data-loss bug, but:
- Pollutes error telemetry / logs with a spurious abort on every stateless
close(). - Users who wire
client.onerrorto alerting/retry logic get spurious triggers. console.errorspam if noonerroris set.
Fix
Catch the abort inside _listChangedLoop so the clean-shutdown path is clean:
try{forawait(constnofthis.subscribe(filter,{ signal })){debounced[n.method]?.();}if(!signal.aborted){thrownewSdkError(SdkErrorCode.ConnectionClosed,'subscriptions/listen stream ended');}}catch(error){if(!signal.aborted)throwerror;// close() aborted the stream — clean shutdown, swallow.}finally{for(consttoftimers.values())clearTimeout(t);timers.clear();}This preserves the existing "stream ended unexpectedly → surface ConnectionClosed" behavior and the existing "stream errored → surface the error" behavior, while making the abort path silent.
| - Prefer `ctx.mcpReq.{elicitInput, requestSampling, listRoots, log}` inside | ||
| handlers; works under both protocols (MRTR under 2026-06). | ||
| See `docs/migration.md` for the full guide. |
There was a problem hiding this comment.
🟡 The changeset added in this PR closes with "See docs/migration.md for the full guide." but docs/migration.md is not modified here and currently has no content covering the 2026-06 stateless model (server/discover, subscriptions/listen, handleHttp, MRTR, etc.). If a release is cut after this PR merges but before the docs PR (#2133) lands, the published changelog will point readers at a guide that doesn't exist — soften the sentence (e.g. "A migration guide will be added to docs/migration.md") or move it to #2133.
Extended reasoning...
What the issue is
.changeset/stateless-2026-06.md is added in this PR and ends with:
See
docs/migration.mdfor the full guide.
This is a forward reference to documentation that this PR does not add. Grepping docs/migration.md (and docs/migration-SKILL.md) for the new surface — stateless, server/discover, subscriptions/listen, 2026-06, DRAFT-2026, handleHttp, MRTR — returns zero matches. Nothing in this diff touches docs/.
Why it matters
Changeset files are the source of release notes: when changesets cuts a release, this prose is published verbatim to the changelog and npm. A reader who follows the link from the published release notes to docs/migration.md will not find a 2026-06 section. The PR description does list #2133 ("docs + changeset") later in the stack, so the docs are clearly planned — but the changeset itself ships here in #2131, not in #2133. The risk window is concrete: if #2131 merges and a release is cut before #2133 lands, the published changelog points at content that doesn't exist.
Step-by-step
- PR [SEP-2575][SEP-2322][SEP-2567] 2026-06 stateless support over StreamableHTTP #2131 merges with
.changeset/stateless-2026-06.mdcontaining the "Seedocs/migration.md" sentence. - A maintainer (or CI) runs
changeset version+changeset publishbefore docs: 2026-06 migration guide + examples + changeset #2133 merges. - The CHANGELOG entries for
@modelcontextprotocol/{core,server,client}now contain a literal "Seedocs/migration.mdfor the full guide." line. - A consumer reading the npm changelog or GitHub release follows the reference and finds no stateless/2026-06 content in
docs/migration.mdat the published tag.
Why this isn't already prevented
There is nothing in CI that cross-checks changeset prose against the diff — this is exactly the class of issue the repo's "Documentation & Changesets" review convention exists to catch (read .changeset/*.md text against the implementation in the same diff and flag claims the diff doesn't back).
How to fix
Pick one of:
- Soften the sentence so it doesn't promise content that doesn't exist yet: "A migration guide will be added to
docs/migration.md." - Move the changeset (or just this sentence) to docs: 2026-06 migration guide + examples + changeset #2133 where the migration guide actually lands.
- Land the migration guide section in this PR.
This is purely a release-notes hygiene / stacked-PR sequencing item — no code impact, and it self-resolves if #2133 lands before any release. Worth a one-line tweak so a release between the two PRs doesn't ship a dangling reference.
| } | ||
| this._instructions = result.instructions; | ||
| if (!this._supportedProtocolVersions.includes(result.protocolVersion)) { | ||
| throw new Error(`Server's protocol version is not supported: ${result.protocolVersion}`); | ||
| } |
There was a problem hiding this comment.
🟡 The legacy _initialize() validation !this._supportedProtocolVersions.includes(result.protocolVersion) now accepts DRAFT-2026-v1 (because this PR added it to SUPPORTED_PROTOCOL_VERSIONS), so a misbehaving server that returns a stateless version from initialize is accepted while _isStateless stays false — leaving the client with a stateless protocol header but legacy request routing. The server side already mirrors the right behavior in _oninitialize() (legacySupported = ...filter(v => !isStatelessProtocolVersion(v))); apply the same filter here.
Extended reasoning...
What the bug is
This PR adds DRAFT_PROTOCOL_VERSION ('DRAFT-2026-v1') to SUPPORTED_PROTOCOL_VERSIONS in packages/core/src/types/constants.ts. That widens the membership check in the client-side legacy handshake _initialize():
if(!this._supportedProtocolVersions.includes(result.protocolVersion)){thrownewError(`Server's protocol version is not supported: ${result.protocolVersion}`);}Before this PR, a server that responded to initialize with a stateless version (e.g. DRAFT-2026-v1) would be rejected. After this PR, that response is accepted — and the client then sets _negotiatedProtocolVersion = 'DRAFT-2026-v1' and transport.setProtocolVersion('DRAFT-2026-v1') while _isStateless remains false.
The asymmetry
The server side of this PR explicitly handles the equivalent case. Server._oninitialize() filters out stateless versions before negotiating, with a comment stating the design intent:
// The legacy initialize handshake never agrees on a stateless (2026+)// version: a client that wants 2026 sends server/discover, not this.constlegacySupported=this._supportedProtocolVersions.filter(v=>!isStatelessProtocolVersion(v));constprotocolVersion=legacySupported.includes(requestedVersion)
? requestedVersion
: (legacySupported[0]??LATEST_PROTOCOL_VERSION);The client-side mirror — the _initialize() membership check — was not given the same filter. The PR did half of the migration.
What goes wrong
After accepting the stateless version over the legacy handshake, the client is in a self-contradictory state:
_negotiatedProtocolVersion === 'DRAFT-2026-v1'— a stateless versiontransport.setProtocolVersion('DRAFT-2026-v1')— every subsequent HTTP request carriesMCP-Protocol-Version: DRAFT-2026-v1_isStateless === false— so_send()falls through toProtocol.request(), which puts no_meta.protocolVersion(or any of the other 2026_metakeys) on outgoing requests
A 2026-06 server that routes by header (WebStandardStreamableHTTPServerTransport.handleRequest) sees MCP-Protocol-Version: DRAFT-2026-v1, sends the request to statelessHttpHandler, and gets a 400 (Missing required _meta.io.modelcontextprotocol/protocolVersion).
Step-by-step proof
- Client connects to a transport with
sendAndReceive._negotiate()sendsserver/discover; the (misbehaving) server returns-32601, so the client falls back. _initialize()sends legacyinitializewithprotocolVersion: '2025-11-25'.- The server (non-SDK, misbehaving) replies with
{ protocolVersion: 'DRAFT-2026-v1', ... }. - Pre-PR:
SUPPORTED_PROTOCOL_VERSIONS.includes('DRAFT-2026-v1')isfalse→ throwsServer's protocol version is not supported. ✅ - Post-PR: the membership check passes →
_negotiatedProtocolVersion = 'DRAFT-2026-v1', transport header set toDRAFT-2026-v1,_isStatelessstillfalse. ❌ - Subsequent
client.listTools()goes throughProtocol.request()→ POST withMCP-Protocol-Version: DRAFT-2026-v1and no_meta.protocolVersion→ server-side router sends it to the stateless handler → 400.
Why this is a nit, not blocking
The trigger requires a non-SDK server that doesn't respond to server/discover but does respond to initialize with a stateless version — a combination the spec doesn't allow and the SDK's own server side prevents (because of the filter quoted above). It's a defensive-consistency gap in a partial migration rather than a bug reachable through any conforming peer.
Fix
Mirror the server-side filter in _initialize():
constlegacySupported=this._supportedProtocolVersions.filter(v=>!isStatelessProtocolVersion(v));if(!legacySupported.includes(result.protocolVersion)){thrownewError(`Server's protocol version is not supported: ${result.protocolVersion}`);}(Or check against STATEFUL_PROTOCOL_VERSIONS directly.) Two lines, brings the client in line with the server's stated invariant that the legacy handshake never agrees on a stateless version.
Implements SEP-2575 (stateless connection model), SEP-2322 (MRTR), and SEP-2567 (per-message routing) over StreamableHTTP.
Server/Clientremain the same classes; each gains a// 2026 statelesssection. New:stateless.ts,subscriptions.ts,statelessHttp.ts,handleHttp.ts,asyncQueue.ts. Transport interface gains optionalsetStatelessHandlers/sendAndReceive.Motivation and Context
2026-06 spec release.
How Has This Been Tested?
pnpm test:all(1367). Conformance vsmodelcontextprotocol/conformance@main: 32 scenarios / 60 checks / 0 failed;server-stateless17/17.Breaking Changes
None to existing API; additive.
@deprecatedJSDoc added to session-dependent top-level methods (still work;ctx.mcpReq.*is the both-protocols path).Types of changes
Checklist