fix(server,client): per-request ctx.log delivery; 2026-era HTTP cancel via stream close; skip unused entry clone

[felixweinberger]

Three small server/client correctness fixes for the 2026-07-28 per-request hosting path. Stacked on #2328.

Motivation and Context

• ctx.mcpReq.log on per-request hosting — handler-emitted log notifications were sent via the session-scoped sendLoggingMessage path, which has no delivery channel under createMcpHandler's per-request model. Server.buildContext now wires log through the request context's ctx.mcpReq.notify (stamping relatedRequestId) so the notification rides the in-flight exchange the same way progress/notify already do. Level filtering branches by era: 2026-era reads the per-request _meta['io.modelcontextprotocol/logLevel'] envelope key (the modern equivalent now that logging/setLevel is removed); legacy-era keeps the existing _loggingLevels map lookup unchanged. The public sendLoggingMessage API is untouched.
• 2026-era HTTP cancel = stream close — the spec wording at the 2026-07-28 revision is "no notifications/cancelled message is required or expected" when the transport carries a per-request stream. Protocol._requestWithSchemaViaCodec now threads a per-request AbortController and aborts it on cancel/timeout when codec.era === MODERN_WIRE_REVISION && transport.hasPerRequestStream; otherwise the legacy notifications/cancelled POST is byte-identical. New optional Transport.hasPerRequestStream flag, set true on StreamableHTTPClientTransport.
• createMcpHandler clone nit — classifyEntryRequest grows a needsForward flag (default true) gating the body-preserving request.clone(); the isLegacyRequest path passes false so the unused forwarding tee is skipped.

How Has This Been Tested?

• core unit tests cover modern×per-request-stream / modern×stdio / legacy×per-request-stream / modern timeout for the cancel path; client test pins hasPerRequestStream
• e2e: protocol:cancel:http-stream-close supersedes the abort-signal / sends-cancellation rows (manifest-only); mcpserver:context:log-from-handler re-admitted to entryStateless + entryModern
• Full gates at this tip: typecheck, lint, core (1207), client (535), server (320), integration (348), e2e (2535p/205xf)

Breaking Changes

None. New optional Transport.hasPerRequestStream flag; existing transports without it keep legacy cancel semantics.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

Changesets + migration.md / migration-SKILL.md entries included for the cancel and log changes.

[changeset-bot]

🦋 Changeset detected

Latest commit: e230a8e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@modelcontextprotocol/core	Minor
@modelcontextprotocol/client	Minor
@modelcontextprotocol/server	Patch

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

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/client@2330

@modelcontextprotocol/codemod

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/codemod@2330

@modelcontextprotocol/server

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/server@2330

@modelcontextprotocol/server-legacy

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/server-legacy@2330

@modelcontextprotocol/express

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/express@2330

@modelcontextprotocol/fastify

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/fastify@2330

@modelcontextprotocol/hono

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/hono@2330

@modelcontextprotocol/node

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/node@2330

commit: e230a8e

[claude]

🔴 The new 2026-era stream-close cancellation mechanism this PR introduces is a no-op for requests sent with RequestOptions.resumptionToken: _send's resumption branch calls _startOrAuthSse({ resumptionToken, replayMessageId }) without threading options.requestSignal (or onRequestStreamEnd), so the per-request abort the protocol layer now relies on is connected to nothing — the resumed stream stays open and no cancel signal of any kind reaches the server. Thread requestSignal/onRequestStreamEnd into that _startOrAuthSse call (or fall back to the legacy path when resumptionToken is set) so the hasPerRequestStream contract added here holds on the resume path too.

Extended reasoning...

What the bug is. This PR routes 2026-era cancellation entirely through TransportSendOptions.requestSignal: in Protocol._requestWithSchemaViaCodec, when codec.era === MODERN_WIRE_REVISION && transport.hasPerRequestStream === true, cancel()/timeout only call requestAbort.abort() and explicitly skip the notifications/cancelled POST (the requestAbort === undefined branch). The new hasPerRequestStream flag added at packages/client/src/client/streamableHttp.ts:267-274 documents the contract this depends on: the transport "honors TransportSendOptions.requestSignal". But StreamableHTTPClientTransport._send's resumption branch (the very first thing it does when options.resumptionToken is set) calls this._startOrAuthSse({ resumptionToken, replayMessageId }) and returns — options.requestSignal and options.onRequestStreamEnd are not passed, even though StartSSEOptions supports both and _startOrAuthSse would honor them (it folds requestSignal into the GET fetch signal and into the no-reconnect / no-onerror gate).\n\nConcrete walk-through. (1) A client on a 2026-07-28 Streamable HTTP connection re-issues a long-running request with callTool(..., { resumptionToken, onresumptiontoken, signal }) — the documented resumability flow. (2) Protocol._requestWithSchemaViaCodec computes streamCloseCancels === true, creates requestAbort, and calls transport.send(outbound, { resumptionToken, requestSignal: requestAbort.signal, ... }). (3) _send hits if (resumptionToken), opens the resumed GET stream via _startOrAuthSse({ resumptionToken, replayMessageId }) — with no requestSignal — and returns. (4) The caller aborts (or the timeout fires); cancel() sees requestAbort !== undefined, so it only calls requestAbort.abort() and never sends notifications/cancelled. (5) Nothing is listening on that signal: the resumed GET stream stays open (and keeps reconnecting on drops), the server keeps working on the request, and only the local promise rejects. The cancel signal is silently lost in every direction.\n\nWhy nothing else catches it. The unit tests added in this PR use a mock PerRequestStreamTransport that merely records requestSignal, and the e2e protocol:cancel:http-stream-close scenario taps tx.send and asserts requestSignal.aborted === true — neither exercises a send that carries a resumptionToken, so the un-wired resume branch is never observed actually tearing a stream down. The legacy notifications/cancelled fallback can't save it either, because the new code skips it whenever requestAbort exists.\n\nOn the refutation (acknowledged, and the framing here is adjusted for it). A verifier correctly points out that pre-PR behavior on this exact path was also broken: the old cancel path sent notifications/cancelled with { resumptionToken, ... } in its send options, and the same resume branch swallowed that message too (it opened another GET instead of POSTing), so the server was not informed before this PR either. That is true — this comment does not claim a behavioral regression in what the server observes. What is attributable to this PR is the contract and the mechanism: the PR (a) introduces hasPerRequestStream with a JSDoc guarantee that the transport honors requestSignal, which is false on the resume path, and (b) makes the protocol layer's only 2026-era cancel signal depend on that guarantee. The spec signal this PR is implementing — "closing the per-request stream IS the cancellation" — is therefore never emitted for resumed requests, which is squarely a gap in the feature being added, not merely a doc nit. The refutation's other point (that "fall back to notifications/cancelled" wouldn't help because the same branch swallows it) is also fair, and is why threading the signal is the right fix rather than the fallback.\n\nImpact and fix. Impact is scoped (2026-era connection + caller-supplied resumptionToken + cancel/timeout) but the failure is silent: the server keeps executing, the resumed SSE stream and its reconnect loop stay alive until transport close, and no error or notification surfaces. The fix is small and local: in the if (resumptionToken) branch of _send, pass requestSignal: options?.requestSignal and onRequestStreamEnd: options?.onRequestStreamEnd through to _startOrAuthSse — _startOrAuthSse and _handleSseStream already do the right thing with both (abort the fetch, suppress the spurious onerror, skip reconnection). A unit test that sends with a resumptionToken on a modern-era connection and asserts the resumed stream is torn down on abort would pin the contract.

[claude]

🔴 On a 2026-era request, ctx.mcpReq.log() sends notifications/message even when the client did not opt in: when the io.modelcontextprotocol/logLevel envelope key is absent, the new code skips the level filter and emits the notification, but the spec says an absent key means the server MUST NOT send any notifications/message for the request. Fix: in the modern-era branch, return early when the envelope carries no logLevel key (the legacy branch is correct as-is).

Extended reasoning...

The bug. The new log callback in Server.buildContext (packages/server/src/server/server.ts:308-330) reads the per-request threshold on a 2026-era request from ctx.mcpReq.envelope?.[LOG_LEVEL_META_KEY] and only suppresses the message when threshold !== undefined && severity < thresholdSeverity. When the envelope does not carry the io.modelcontextprotocol/logLevel key at all, threshold is undefined, the filter is skipped entirely, and ctx.mcpReq.notify({ method: 'notifications/message', ... }) is sent. In other words, absence of the key is treated as "no filter — send everything."\n\nWhy that is the inverse of the spec. The repo's own 2026-07-28 spec material is explicit that absence means opt-out, not opt-in. packages/core/src/types/spec.types.2026-07-28.ts (~lines 100-110) documents the io.modelcontextprotocol/logLevel key: "If absent, the server MUST NOT send any notifications/message notifications for this request. The client opts in to log messages by explicitly setting a level. Replaces the former logging/setLevel RPC." The same MUST-NOT wording is repeated on LOG_LEVEL_META_KEY in constants.ts and in the 2026 wire schemas (rev2026-07-28/schemas.ts), where the key is .optional() — so an absent key is the legal, common case.\n\nWhy the default path actually hits this. The SDK client never auto-attaches a logLevel envelope key: Client._outboundMetaEnvelope only adds protocolVersion/clientInfo/clientCapabilities. So an ordinary 2026-era SDK client that has not opted in will receive notifications/message from any handler that calls ctx.mcpReq.log. There is no other filter on this path: assertNotificationCapability only checks the server's own logging capability, and the session-scoped isMessageIgnored/sendLoggingMessage filtering is bypassed because the new code goes straight to ctx.mcpReq.notify.\n\nStep-by-step proof.\n1. A 2026-era client (e.g. one connected via createMcpHandler's modern path) calls tools/call with the required _meta envelope but no io.modelcontextprotocol/logLevel key — exactly what the SDK Client produces by default.\n2. The protocol layer lifts the envelope; ctx.mcpReq.envelope contains protocolVersion/clientInfo/clientCapabilities but no logLevel key.\n3. The tool handler calls ctx.mcpReq.log('debug', 'some message').\n4. In the new log callback, this._servedModernEra() is true, so threshold = ctx.mcpReq.envelope?.[LOG_LEVEL_META_KEY] evaluates to undefined.\n5. The guard if (threshold !== undefined && ...) is false, so the early return is skipped.\n6. ctx.mcpReq.notify({ method: 'notifications/message', ... }) rides the per-request stream to a client that never opted in — a direct violation of the spec's MUST NOT.\n\nNotably, the re-admitted e2e row mcpserver:context:log-from-handler on entryModern (handler-context.test.ts) uses a default Client that never sets a logLevel, so that test passes only by virtue of this violation — it pins the wrong behavior on the modern cell.\n\nWhy the existing code doesn't prevent it / why legacy is fine. On the 2025 era the "no level set ⇒ send" posture is correct (that was the logging/setLevel semantics, and the legacy branch reads this._loggingLevels), but the same posture transplanted onto the 2026 envelope key inverts the new opt-in model. The 2026-07-28 LoggingMessageNotification doc reiterates the opt-in semantics.\n\nFix. In the modern-era branch, return early (Promise.resolve()) when ctx.mcpReq.envelope?.[LOG_LEVEL_META_KEY] is undefined; only when a level is present should the severity comparison run. The e2e expectation for entryModern should then either set a logLevel in the request envelope or assert that no notifications/message is delivered without one.

[claude]

🔴 Routing every ctx.mcpReq.log() through ctx.mcpReq.notify() stamps relatedRequestId on legacy (2025-era) sessionful Streamable HTTP transports too, moving handler logs off the session-scoped standalone/eventStore channel onto the in-flight request's POST SSE stream — and after ctx.http.closeSSE() that stream is gone from _streamMapping, so a log emitted before the client reconnects is silently dropped instead of stored for replay (the SEP-1699 sse-polling flow). The only coverage of that flow is excluded from run:examples in this same PR, and the changeset/migration docs present legacy behavior as unchanged. Either keep the session-scoped sendLoggingMessage routing for legacy-era requests (use ctx.mcpReq.notify only on the modern/per-request path), or make the related-request branch store-while-disconnected and document the legacy delivery-channel change rather than excluding the example.

Extended reasoning...

What changes. Pre-PR, ctx.mcpReq.log() delegated to this.sendLoggingMessage() → Protocol.notification(), which carries no relatedRequestId. Post-PR, the new log callback in Server.buildContext (packages/server/src/server/server.ts:324-330) returns ctx.mcpReq.notify(...), and the protocol layer always stamps relatedRequestId: request.id on related notifications — for both eras, not just the per-request hosting path the PR is motivated by.

Why that matters on a legacy sessionful transport. In WebStandardStreamableHTTPServerTransport.send() the routing is keyed entirely on relatedRequestId (packages/server/src/server/streamableHttp.ts:960-1014):

• No relatedRequestId (the old behavior): the message takes the standalone-stream branch, where it is stored in the eventStore even while the stream is disconnected ("Store even if stream is disconnected so events can be replayed on reconnect", lines 976-988) and otherwise written to the standalone GET stream — which closeSSE() never touches.
• With relatedRequestId (the new behavior): the message takes the per-request branch, where eventStore.storeEvent and the write happen only inside if (!this._enableJsonResponse && stream?.controller && stream?.encoder) (lines 1005-1014). closeSSEStream(requestId) calls stream.cleanup(), which removes the stream from _streamMapping (lines 939-947) — so once the request stream has been closed, a handler log is neither delivered nor stored. It is silently dropped.

Step-by-step proof (the SEP-1699 sse-polling example). examples/sse-polling/server.ts runs exactly this flow on a sessionful 2025-era transport with an eventStore: (1) the tool handler logs early progress, (2) calls ctx.http.closeSSE() to close the request's SSE stream (~400ms), (3) logs 'Progress: 75%' ~200ms later while the client is still waiting out its 300ms retryInterval, (4) the client reconnects with Last-Event-ID and client.ts asserts the 75% line was delivered/replayed. Pre-PR, step 3's notification went out without relatedRequestId, so it was stored under the standalone stream id regardless of connection state and replayed on reconnect — the assertion held deterministically. Post-PR, step 3's notification carries relatedRequestId, hits the per-request branch with the stream already cleaned up, and is dropped unless the client's reconnect happens to win the race. The example's outcome is now a timing coin-flip.

Why nothing in the PR catches it — and the documentation gap. This same PR adds "excluded": "replay assertion is timing-sensitive on CI; revisit" to examples/sse-polling/package.json, i.e. the only coverage of the affected behavior is disabled in the PR that changes it. The exclusion commit's own message (fd07235) is more candid than the package.json prose: "the request-related routing change lands before the store-first fix, so the post-disconnect log is not reliably replayed on intermediate commits" — the regression is acknowledged but neither fixed nor documented. Meanwhile the changeset (.changeset/server-ctx-log-request-related.md) frames the change as making handler logs delivered "instead of being silently dropped", the PR description says legacy keeps only "the existing _loggingLevels map lookup unchanged" and declares "Breaking Changes: None", and migration.md / migration-SKILL.md only cover the cancel change. None of them mention that on a legacy sessionful transport the delivery channel — and, with closeSSE/eventStore or enableJsonResponse, deliverability itself — changes.

Impact. Any existing legacy sessionful deployment that uses ctx.mcpReq.log() together with closeSSE()+eventStore (the documented SEP-1699 polling pattern) loses log notifications emitted while the request stream is closed; the same applies on enableJsonResponse transports, where the per-request branch never writes notifications at all. These are messages that previously reached the client or were buffered for replay, now dropped with no error.

Fix. Either (a) scope the new routing to the path that needs it: in the log callback, use ctx.mcpReq.notify only when this._servedModernEra() (or when there is no session-wide channel), and keep the previous sendLoggingMessage() session-scoped routing for legacy-era requests; or (b) land the store-while-disconnected fix for the related-request branch in send() together with this change, document the legacy delivery-channel change in the changeset and migration docs, and re-enable the sse-polling example instead of excluding it.

[claude]

🔴 The legacy-era branch of the new ctx.mcpReq.log filter looks up the threshold with this._loggingLevels.get(undefined), but logging/setLevel stores the level keyed by the transport session id — so on a sessionful 2025-era connection a client's logging/setLevel('error') is never consulted and every ctx.mcpReq.log('debug', ...) message is delivered. The pre-PR sendLoggingMessage delegation had the same hole (no behavioral regression), but this PR rewrites the filter inline with ctx.sessionId in scope and adds a comment claiming the session-scoped level "applies exactly as before"; the lookup should be this._loggingLevels.get(ctx.sessionId) ?? this._loggingLevels.get(undefined) (or just reuse isMessageIgnored(level, ctx.sessionId)).

Extended reasoning...

What the bug is. The new inline log callback in Server.buildContext (packages/server/src/server/server.ts:308-330) branches the level filter by era. On the legacy (2025-era) branch it reads the threshold with this._loggingLevels.get(undefined). However, the logging/setLevel handler installed by _registerLoggingHandler (server.ts:286-293) stores the client's chosen level keyed by the transport session id — ctx.sessionId or the mcp-session-id header. On any sessionful 2025-era Streamable HTTP connection the level therefore lives under the session-id key, the get(undefined) lookup returns undefined, the threshold !== undefined guard is skipped, and the notification is always emitted.

Concrete walk-through.

1. A client connects over a sessionful 2025-era Streamable HTTP transport to a server with the logging capability; the transport assigns session id abc.
2. The client sends logging/setLevel { level: 'error' }. The handler computes transportSessionId = 'abc' and stores _loggingLevels.set('abc', 'error').
3. A tool handler calls ctx.mcpReq.log('debug', 'verbose detail').
4. In the new log callback, this._servedModernEra() is false (legacy connection), so threshold = this._loggingLevels.get(undefined) → undefined (the only entry is keyed 'abc').
5. The filter if (threshold !== undefined && severity < thresholdSeverity) is skipped, and ctx.mcpReq.notify({ method: 'notifications/message', params: { level: 'debug', ... } }) goes out — even though the client explicitly asked for error and above only.

Why nothing else prevents it. The only other check on this path is assertNotificationCapability('notifications/message'), which validates the server's logging capability, not the client's level. The session-keyed filtering logic that does the right thing — isMessageIgnored(level, sessionId) at server.ts:352-355 — is bypassed because the new code no longer routes through sendLoggingMessage.

Why this belongs in this PR. To be clear about scope: the pre-PR code (log: (level, data, logger) => this.sendLoggingMessage({ level, data, logger }) with no sessionId argument → isMessageIgnored(level, undefined)) had exactly the same lookup hole, so this is not a behavioral regression introduced here. But the PR rewrites this exact filter inline, has ctx.sessionId directly in scope, and adds a comment asserting that on 2025-era connections "the session-scoped level set via logging/setLevel applies exactly as before" — when the session-scoped level is in fact never read on this path. The ServerContext.log JSDoc in protocol.ts likewise promises "Respects the client's log level filter set via logging/setLevel". With the code being rewritten and re-documented here, this is the natural — and trivial — place to close the gap.

Impact. Sessionful legacy clients that lower their log verbosity via logging/setLevel still receive every handler-emitted log message (debug/info noise on the wire), contradicting both the spec semantics of logging/setLevel and the SDK's documented contract for ctx.mcpReq.log.

Fix. In the legacy branch, change the lookup to this._loggingLevels.get(ctx.sessionId) ?? this._loggingLevels.get(undefined) (the fallback covers stateless transports where setLevel was stored under undefined), or simply replace the inline comparison with the existing this.isMessageIgnored(level, ctx.sessionId) helper, which already performs the session-keyed lookup and severity comparison.