Terminate cancelled requests in-band on the legacy HTTP wire

Review of the first revision showed that dropping the cancellation
frame outright fought the 2025-era streamable HTTP wire, whose per-request
SSE stream is the ordered, resumable channel for everything about that
request and ends only when a response for its id passes through it. The
out-of-band substitutes each broke something: the transport hook closed
the stream from the side and could overtake messages already queued
through the router (notably the courtesy cancel for a handler's nested
elicitation), had no durable form so a resuming client's replay tailed
forever, and needed two dispatcher call sites; the client aborting its
own POST severed the delivery path for that owed related traffic and
turned routine cancellation into a write against a closed socket.

The 2026-07-28 MUST NOT that motivates this change never coexists with
resumable per-request streams (SEP-2575 removed them), so the fix is
scoped by era instead. The dispatcher stays strictly silent for a
cancelled request everywhere. The one 2025-era transport terminates the
settled request through the same ordered channel with a valid -32800
REQUEST_CANCELLED error (LSP's RequestCancelled) in place of the old
code 0 - so ordering, resumption, and the client's channel are all
preserved by construction, and old and new clients complete the same way
they did before. The client transport is unchanged from main; the
dispatcher settles a cancelled request at a single site, containing a
raising transport hook like its other callback boundaries.

Author: maxisbey

docs/migration.md

@@ -1390,11 +1390,11 @@ Previously it also re-raised exceptions yielded by the transport onto the read s
 
 ### Cancelled requests are no longer answered
 
-In v1, when the peer sent `notifications/cancelled` for an in-flight request, the receiving side interrupted the handler and answered the request anyway with a JSON-RPC error, `{"code": 0, "message": "Request cancelled"}`. The 2026-07-28 spec says a server MUST NOT send any further messages for a cancelled request, and the sender is expected to stop waiting once it cancels, so that error response has been removed: a cancelled request now produces no response at all - no result, and no error, even if the handler runs to completion or fails afterwards. This applies to both seats (the server for cancelled client requests, and the client for cancelled server-initiated requests such as sampling or elicitation).
+In v1, when the peer sent `notifications/cancelled` for an in-flight request, the receiving side interrupted the handler and answered the request anyway with a JSON-RPC error, `{"code": 0, "message": "Request cancelled"}` - and `0` is not a defined JSON-RPC error code. The 2026-07-28 transport specifications (stdio, streamable HTTP) say a server **MUST NOT** send any further messages for a cancelled request; the older cancellation pattern already said it **SHOULD NOT**. The sender is expected to stop waiting once it cancels, so that error response has been removed: a cancelled request now produces no response at all - no result, and no error - even if the handler runs to completion or fails afterwards. This applies to both seats (the server for cancelled client requests, and the client for cancelled server-initiated requests such as sampling or elicitation).
 
-On the 2025-era streamable HTTP wire, the cancelled request's HTTP exchange still ends rather than staying open: JSON-response mode answers the POST with an empty `202 Accepted`, SSE mode ends the event stream without a response event, and the client tears down the abandoned request's own POST.
+The one deliberate exception is the 2025-era streamable HTTP transport (`StreamableHTTPServerTransport`), whose wire can end a request's stream only with a response for that id (and stores that response so a resuming client's replay terminates too). Under the 2025 rule, a SHOULD NOT, that transport now terminates a cancelled request with a valid `-32800` error (`mcp.server.streamable_http.REQUEST_CANCELLED`, mirroring LSP's `RequestCancelled`) in place of the old `0`. Nothing else answers.
 
-Nothing changes for callers of the built-in client: abandoning a call (cancelling the awaiting task, or a per-request timeout) never waited for that response. If you send `notifications/cancelled` by hand while still awaiting the call, the call no longer resolves with the code-0 error; stop awaiting it yourself, or use a per-request timeout.
+Nothing changes for callers of the built-in client: abandoning a call (cancelling the awaiting task, or a per-request timeout) never waited for that response. If you send `notifications/cancelled` by hand while still awaiting the call, the call now receives nothing on most transports (over 2025-era streamable HTTP it fails with `REQUEST_CANCELLED`); stop awaiting it yourself, or use a per-request timeout.
 
 ### `Server.run()` no longer takes a `stateless` flag
 

examples/stories/streaming/README.md

@@ -56,10 +56,12 @@ uv run python -m stories.streaming.client --http --server server_lowlevel
   OpenTelemetry instead of `notifications/message`. It is shown here because
   servers still need to support 2025-era clients during that window. Progress
   and cancellation are **not** deprecated. TODO(maxisbey): revisit before beta.
-- When a request is cancelled the server currently replies with
-  `ErrorData(code=0, message="Request cancelled")`; the spec says it should not
-  reply at all. The client never observes it (its awaiting task is already
-  cancelled), so this story does not assert on the reply.
+- A cancelled request is not answered: no response follows
+  `notifications/cancelled`. (The 2025-era streamable HTTP transport is the one
+  exception - its wire ends a request only with a response, so it terminates
+  with a `-32800` `REQUEST_CANCELLED` error.) The client never observes any of
+  this - its awaiting task is already cancelled - so this story does not assert
+  on it.
 
 ## Spec
 

src/mcp/client/streamable_http.py

@@ -102,12 +102,12 @@ def __init__(self, url: str) -> None:
         # scheduling is arbitrary). Reused on outbound HTTP that carries no
         # per-message header (transport-internal GET/DELETE, and dispatcher-written
         # response/error POSTs that bypass the session's stamp), and consulted by
-        # `_apply_outbound_cancellation`. Cleared when an `initialize` message is
+        # `_consume_modern_cancellation`. Cleared when an `initialize` message is
         # dequeued so a probe-stamped value cannot leak onto the handshake.
         self._protocol_version_header: str | None = None
         # Every request's POST runs inside one of these so an outbound
-        # `notifications/cancelled` can abort it; see
-        # `_apply_outbound_cancellation`. Keys are verbatim-typed ("1" is not 1).
+        # `notifications/cancelled` at 2026 can abort it; see
+        # `_consume_modern_cancellation`. Keys are verbatim-typed ("1" is not 1).
         self._in_flight_posts: dict[RequestId, _InFlightPost] = {}
 
     def _prepare_headers(self) -> dict[str, str]:
@@ -268,28 +268,32 @@ async def _handle_resumption_request(self, ctx: RequestContext) -> None:
                     await event_source.response.aclose()
                     break
 
-    def _apply_outbound_cancellation(self, session_message: SessionMessage) -> bool:
-        """Apply an outbound `notifications/cancelled` to this transport; True means "do not POST".
-
-        The dispatcher emits the frame as its abandon signal (it only ever names
-        one of our own request ids), so the named request's in-flight POST is
-        aborted at every era: its caller is gone and the stream must not linger
-        or resume. The POST's recorded era only decides whether the frame is also
-        POSTed - at 2026 the abort IS the cancellation signal and there are no
-        client-to-server notifications (swallow); at 2025 the frame is the signal,
-        so it is POSTed too. With no POST to consult, the cached negotiated version
-        decides; at 2026 the frame is swallowed even unmatched, so a late cancel
-        racing the response cannot leak onto the wire.
+    def _consume_modern_cancellation(self, session_message: SessionMessage) -> bool:
+        """Translate an outbound `notifications/cancelled` at 2026; True means "do not POST".
+
+        The 2026 wire defines no client-to-server notifications over streamable
+        HTTP: closing a request's response stream IS its cancellation signal.
+        The dispatcher still emits the courtesy frame as its abandon signal
+        (every outbound cancel names one of our own request ids - the spec
+        forbids cancelling a request the sender did not issue), so this
+        transport translates it: when the named request's POST is in flight,
+        that POST's own recorded era decides - abort-and-swallow at 2026, POST
+        the frame below it (where the frame is the signal and a disconnect
+        explicitly is not). With no POST to consult, the cached negotiated
+        version decides; at 2026 the frame is swallowed even unmatched, so a
+        late cancel racing the response cannot leak onto the wire.
         """
         message = session_message.message
         if not (isinstance(message, JSONRPCNotification) and message.method == "notifications/cancelled"):
             return False
         request_id = cancelled_request_id_from_params(message.params)
         post = self._in_flight_posts.get(request_id) if request_id is not None else None
         if post is not None:
+            if not post.modern:
+                return False
             logger.debug("aborting in-flight POST for cancelled request %r", request_id)
             post.scope.cancel()
-            return post.modern
+            return True
         return self._protocol_version_header in MODERN_PROTOCOL_VERSIONS
 
     async def _run_request_post(
@@ -298,7 +302,7 @@ async def _run_request_post(
         post: _InFlightPost,
         request_id: RequestId,
     ) -> None:
-        """Run one request's POST inside its abort scope (see `_apply_outbound_cancellation`)."""
+        """Run one request's POST inside its abort scope (see `_consume_modern_cancellation`)."""
         try:
             with post.scope:
                 await post_fn()
@@ -544,7 +548,7 @@ async def post_writer(
 
                 async def _handle_message(session_message: SessionMessage) -> None:
                     message = session_message.message
-                    if self._apply_outbound_cancellation(session_message):
+                    if self._consume_modern_cancellation(session_message):
                         return
                     metadata = (
                         session_message.metadata

src/mcp/server/streamable_http.py

@@ -65,6 +65,13 @@
 # whole session on a lazily-started `sse_writer`. See #1764.
 REQUEST_STREAM_BUFFER_SIZE: Final = 16
 
+# Error code answering a request that settled without a response (e.g. it was
+# cancelled) on this 2025-era wire, which ends a request's stream only with a
+# response. Mirrors LSP's RequestCancelled; not sent by the 2026 transports, where
+# the spec forbids answering a cancelled request. See
+# `StreamableHTTPServerTransport._terminate_unanswered_request`.
+REQUEST_CANCELLED: Final = -32800
+
 # Session ID validation pattern (visible ASCII characters ranging from 0x21 to 0x7E)
 # Pattern ensures entire string contains only valid characters by using ^ and $ anchors
 SESSION_ID_PATTERN = re.compile(r"^[\x21-\x7E]+$")
@@ -252,7 +259,7 @@ def close_standalone_sse_stream(self) -> None:
 
     def _create_session_message(
         self,
-        message: JSONRPCMessage,
+        message: JSONRPCRequest,
         request: Request,
         request_id: RequestId,
         protocol_version: str,
@@ -262,10 +269,10 @@ def _create_session_message(
         The close_sse_stream callbacks are only provided when the client supports
         resumability (protocol version >= 2025-11-25). Old clients can't resume if
         the stream is closed early because they didn't receive a priming event.
-        Every request carries `on_request_unanswered`, which ends its stream
-        when the request settles without a response.
+        Every request carries `on_request_unanswered`, so a request that settles
+        without a response is still terminated on this era's wire.
         """
-        end_stream = partial(self._end_request_stream, request_id)
+        end_stream = partial(self._terminate_unanswered_request, message.id)
         # Only provide close callbacks when client supports resumability
         if self._event_store and is_version_at_least(protocol_version, "2025-11-25"):
 
@@ -394,15 +401,19 @@ def _create_event_data(self, event_message: EventMessage) -> SSEEvent:
 
         return event_data
 
-    async def _end_request_stream(self, request_id: RequestId) -> None:
-        """End a request's stream when it settled without a response (e.g. cancelled).
+    async def _terminate_unanswered_request(self, request_id: RequestId) -> None:
+        """Terminate a request that settled without a response (e.g. cancelled).
 
-        Only the send side, so the reader finishes as a normal end-of-stream: JSON
-        mode answers the POST with 202, SSE mode ends the event stream. Already
-        gone if `close_sse_stream()` polling or session teardown released it first.
+        The 2025-era wire ends a request's stream only with a response for its
+        id - and stores that response so a resuming client's replay terminates
+        too - so this era answers a cancelled request with `REQUEST_CANCELLED`
+        where the dispatcher itself stays silent (the 2026 transports MUST NOT
+        answer). It is written through the same ordered channel as the request's
+        other messages, so it cannot overtake anything already queued for it.
         """
-        if streams := self._request_streams.get(request_id):  # pragma: no branch
-            await streams[0].aclose()
+        assert self._write_stream is not None  # a dispatched request implies connect() ran
+        error = ErrorData(code=REQUEST_CANCELLED, message="Request cancelled")
+        await self._write_stream.send(SessionMessage(JSONRPCError(jsonrpc="2.0", id=request_id, error=error)))
 
     async def _clean_up_memory_streams(self, request_id: RequestId) -> None:
         """Clean up memory streams for a given request ID."""
@@ -571,7 +582,7 @@ async def _handle_post_request(self, scope: Scope, request: Request, receive: Re
                 # Process the message
                 metadata = ServerMessageMetadata(
                     request_context=request,
-                    on_request_unanswered=partial(self._end_request_stream, request_id),
+                    on_request_unanswered=partial(self._terminate_unanswered_request, message.id),
                 )
                 session_message = SessionMessage(message, metadata=metadata)
                 await writer.send(session_message)
@@ -590,15 +601,19 @@ async def _handle_post_request(self, scope: Scope, request: Request, receive: Re
                         else:  # pragma: no cover
                             logger.debug(f"received: {event_message.message.method}")
 
+                    # At this point we should have a response
                     if response_message:
                         # Create JSON response
                         response = self._create_json_response(response_message)
-                    else:
-                        # The stream ended without a response: the request settled
-                        # unanswered (e.g. it was cancelled). End the POST with
-                        # an empty 202 Accepted rather than leaving it open.
-                        response = self._create_json_response(None, HTTPStatus.ACCEPTED)
-                    await response(scope, receive, send)
+                        await response(scope, receive, send)
+                    else:  # pragma: no cover
+                        # This shouldn't happen in normal operation
+                        logger.error("No response message received before stream closed")
+                        response = self._create_error_response(
+                            "Error processing request: No response received",
+                            HTTPStatus.INTERNAL_SERVER_ERROR,
+                        )
+                        await response(scope, receive, send)
                 except Exception:  # pragma: no cover
                     logger.exception("Error processing JSON response")
                     response = self._create_error_response(

src/mcp/shared/jsonrpc_dispatcher.py

@@ -704,6 +704,7 @@ async def _handle_request(
         instead, and `_settle_unanswered` tells the transport.
         """
         answer_write_started = False
+        handler_failure: BaseException | None = None  # re-raised once the request settles
         try:
             with scope:
                 try:
@@ -724,10 +725,6 @@ async def _handle_request(
                     # would break JSON-RPC.
                     answer_write_started = True
                     await self._write_result(req.id, result)
-            # Reached unanswered: the handler saw the cancel (any mode), or the
-            # scope absorbed the interrupt at __exit__.
-            if not answer_write_started:
-                await self._settle_unanswered(dctx)
         except anyio.get_cancelled_exc_class():
             # Shutdown: answer the request so the peer isn't left waiting - unless
             # an answer write already started (it may have reached the transport;
@@ -744,19 +741,24 @@ async def _handle_request(
             raise
         except Exception as e:
             error = handler_exception_to_error_data(e)
-            unmapped = error is None
-            if unmapped:
+            if error is None:
                 logger.exception("handler for %r raised", req.method)
                 # TODO(L58): code=0 pins existing-server compat; JSON-RPC says
                 # INTERNAL_ERROR. Revisit per the suite's divergence entry.
                 error = ErrorData(code=0, message=str(e))
+                if self._raise_handler_exceptions:
+                    handler_failure = e
             # A cancel silences only the wire; the failure stays as visible as before.
-            if dctx.cancel_requested.is_set():
-                await self._settle_unanswered(dctx)
-            else:
+            if not dctx.cancel_requested.is_set():
+                answer_write_started = True
                 await self._write_error(req.id, error)
-            if unmapped and self._raise_handler_exceptions:
-                raise
+        # The one place a cancelled request settles: the handler is done (any
+        # mode) with nothing written. A peer-interrupt cancel is absorbed at
+        # scope __exit__ and lands here too.
+        if not answer_write_started:
+            await self._settle_unanswered(dctx)
+        if handler_failure is not None:
+            raise handler_failure
         # No `_in_flight` pop here: the inner finally covers every path, and a late pop could evict a reused id.
 
     def _allocate_id(self) -> int:
@@ -781,12 +783,19 @@ async def _write_error(self, request_id: RequestId, error: ErrorData) -> None:
     async def _settle_unanswered(self, dctx: _JSONRPCDispatchContext[TransportT]) -> None:
         """Run the transport's `on_request_unanswered` hook: this request settled with no response.
 
-        A shared-channel wire (stdio) has none; legacy streamable HTTP uses it
-        to complete the request's still-open POST.
+        The dispatcher writes nothing for it; a transport whose wire must still
+        end the request (2025-era streamable HTTP) does so from this hook. A
+        raising hook is contained here, like the other callback boundaries.
         """
         metadata = dctx.message_metadata
-        if isinstance(metadata, ServerMessageMetadata) and metadata.on_request_unanswered is not None:
+        if not isinstance(metadata, ServerMessageMetadata) or metadata.on_request_unanswered is None:
+            return
+        try:
             await metadata.on_request_unanswered()
+        except (anyio.BrokenResourceError, anyio.ClosedResourceError):
+            logger.debug("on_request_unanswered dropped: connection closing")
+        except Exception:
+            logger.exception("on_request_unanswered hook raised")
 
     async def _final_write(
         self,

src/mcp/shared/message.py

@@ -41,8 +41,9 @@ class ServerMessageMetadata:
     close_sse_stream: CloseSSEStreamCallback | None = None
     # Callback to close the standalone GET SSE stream (for unsolicited notifications)
     close_standalone_sse_stream: CloseSSEStreamCallback | None = None
-    # Callback for a request that settles without a response (e.g. cancelled),
-    # so the transport can end the per-request state a response would have closed.
+    # Callback the dispatcher runs when this request settles without a response
+    # (e.g. it was cancelled), for a transport whose wire must still end the
+    # request even though no response is written.
     on_request_unanswered: Callable[[], Awaitable[None]] | None = None