Fail fast on request-scoped server requests in JSON-response mode

In stateful JSON-response mode a tool handler calling ctx.elicit()
(or any server-to-client request tied to the in-flight call) hung
forever: the loop dispatcher reported can_send_request=True, the
request was routed into the call's own per-request queue, and the JSON
POST drain loop silently discarded it, so the parked waiter never woke.

The transport now supplies each message's TransportContext
(StreamableHTTPServerTransport.transport_context_for): it owns what a
request's response can carry, so can_send_request is False in
JSON-response mode and the request raises NoBackChannelError at once -
the same fail-fast the stateless path and the 2026-07-28 entries already
have. serve_loop takes the builder as a keyword and the session manager
passes it for both the stateful and stateless legs. The session's
standalone GET stream is untouched and still carries unrelated messages.

Author: maxisbey

docs/migration.md

@@ -629,7 +629,7 @@ Transport-specific parameters have been moved from the `MCPServer` constructor t
 - `host`, `port` - HTTP server binding
 - `sse_path`, `message_path` - SSE transport paths
 - `streamable_http_path` - StreamableHTTP endpoint path
-- `json_response`, `stateless_http` - StreamableHTTP behavior
+- `json_response`, `stateless_http` - StreamableHTTP behavior (each also removes a server-to-client channel; mid-request server requests then raise `NoBackChannelError`, see the `Server.run()` entry below)
 - `max_request_body_size` - StreamableHTTP request-body limit
 - `event_store`, `retry_interval` - StreamableHTTP event handling
 - `transport_security` - DNS rebinding protection
@@ -812,8 +812,11 @@ enforce the spec's egress rule: an undeclared capability (form-mode `elicitation
 or `tool_choice`) fails the call with a `-32021`
 `MISSING_REQUIRED_CLIENT_CAPABILITY` JSON-RPC error instead of sending a
 request the client cannot handle. This applies on 2025-11-25 sessions with a
-live back-channel too; a session with no back-channel keeps failing with its
-no-back-channel error. To migrate, declare the capability: the SDK client
+live back-channel too; a pre-`2026-07-28` session with no back-channel
+(stateless HTTP, or streamable HTTP with `json_response=True`) keeps failing
+with its no-back-channel error. At `2026-07-28` a resolver never uses a
+back-channel — it answers with an `InputRequiredResult` — so the `-32021`
+check applies there unconditionally. To migrate, declare the capability: the SDK client
 declares `elicitation`, `sampling`, and `roots` when the matching callback is
 set, and `sampling.tools` needs an explicit
 `Client(sampling_capabilities=SamplingCapability(tools=...))`. Direct
@@ -1388,11 +1391,11 @@ The method and the raw inbound params are `ctx.method` and `ctx.params` (`params
 
 Previously it also re-raised exceptions yielded by the transport onto the read stream (e.g. JSON parse errors). Those are now debug-logged and dropped regardless of `raise_exceptions`. If you relied on `run()` exiting on a transport-level parse error, that no longer happens.
 
-### `Server.run()` no longer takes a `stateless` flag
+### `Server.run()` no longer takes a `stateless` flag; no-back-channel requests raise `NoBackChannelError`
 
 The `stateless: bool` parameter on the lowlevel `Server.run()` has been removed. Stateless serving is now a property of how the connection is constructed (the streamable-HTTP manager builds a born-ready `Connection` per request), not a flag the loop driver inspects.
 
-Server-initiated requests that have no channel to travel on now raise `NoBackChannelError` (an `MCPError` subclass) — the same exception regardless of why the channel is absent. In v1 there was no dedicated exception for this case: the transport silently dropped the outbound message and the awaiting call stalled.
+Server-initiated requests that have no channel to travel on now raise `NoBackChannelError` (an `MCPError` subclass) — the same exception regardless of why the channel is absent. The request-scoped channel of a stateful streamable-HTTP session running with `json_response=True` is one of those cases: a JSON body carries exactly one response, so a mid-request `ctx.elicit()` (or any server-to-client request tied to the in-flight call) fails fast with `NoBackChannelError` — an `INVALID_REQUEST` protocol error at the client — instead of stalling the `POST`; request-scoped notifications are dropped as before, and unrelated notifications still ride the standalone `GET` stream. In v1 there was no dedicated exception for this case: the transport silently dropped the outbound message and the awaiting call stalled.
 
 ### Lowlevel `Server`: `request_context` property removed
 

docs/run/index.md

@@ -65,7 +65,7 @@ Each transport has its own keyword arguments, all on `run()`:
 
 * `host` / `port`: where to listen. Defaults `127.0.0.1` and `8000`.
 * `streamable_http_path`: where the MCP endpoint lives. Default `/mcp`.
-* `json_response=True`: answer with plain JSON instead of an SSE stream.
+* `json_response=True`: answer each POST with a single JSON body instead of an SSE stream. That body has room for the response and nothing else, so a tool that calls back into the client mid-request (`ctx.elicit()`, sampling) raises `NoBackChannelError` on this leg, and notifications tied to the in-flight call (progress from `ctx.report_progress()`, per-call log messages) are dropped; the standalone `GET` stream still carries unrelated ones.
 * `stateless_http=True`: a fresh transport per request, no session tracking.
 * `max_request_body_size`: largest accepted POST body in bytes. Defaults to 4 MiB; larger requests
   receive HTTP 413 before parsing or session creation. Raise it only when legitimate MCP messages

docs/run/legacy-clients.md

@@ -72,6 +72,13 @@ Two things about it matter more than what it does.
 
 **It costs both server-to-client channels on that leg.** A session that lives for one `POST` has no stream for the server to push a request down and no standalone stream for it to push notifications down. Every server-initiated request raises `NoBackChannelError`: `ctx.elicit()`, the retired sampling and roots calls (**[Deprecated features](../deprecated.md)**), and, yes, `Resolve` asking a *legacy* client its question. Notifications don't even get an error; they are silently dropped.
 
+!!! note
+    `json_response=True` is not that knob, but it takes half the same cost on *every* legacy
+    session: a `POST` answered with one JSON body has no stream for the request-scoped channel,
+    so a mid-request `ctx.elicit()` raises the same `NoBackChannelError` and notifications tied to
+    the request are dropped. The session's standalone stream is untouched: unrelated notifications
+    still arrive.
+
 !!! check
     Do the wrong thing. `reserve` is the exact tool that just served both clients. Deploy it with
     `stateless_http=True`, connect the same two clients over HTTP, and call it from each.

docs/troubleshooting.md

@@ -305,7 +305,7 @@ You see this one from `ctx.elicit()` on a legacy connection, and on any connecti
 
 ## `MCPError: Cannot send 'elicitation/create': this transport context has no back-channel for server-initiated requests.`
 
-Your handler tried to reach the client mid-request, on a connection where nothing can carry a request from the server. There are exactly two ways to be on one.
+Your handler tried to reach the client mid-request, on a connection whose call has no channel that can carry a request from the server. There are three server configurations that put a call there.
 
 **A `2026-07-28` connection: any transport, always.** The modern protocol has no server-initiated requests at all, so the server refuses before anything is sent. `ctx.elicit()` inside a tool is the classic way to meet this (on the very first in-memory test, since `Client(server)` negotiates `2026-07-28` without being asked), and passing `elicitation_callback=` changes nothing, because no request ever reaches the client for it to answer:
 
@@ -329,20 +329,23 @@ mcp.shared.exceptions.MCPError: Cannot send 'elicitation/create': this transport
 --8<-- "docs_src/troubleshooting/tutorial008.py"
 ```
 
+**A legacy connection on a `json_response=True` server.** The `POST` is answered with one JSON body, and one body carries only the response, so the request-scoped stream a mid-request `ctx.elicit()` needs does not exist here either. The session, its `Mcp-Session-Id`, and its standalone stream are all still there; only the request-scoped channel is gone.
+
 The message names the method it could not send. `NoBackChannelError` is the class the server raises, but the wire carries only the base `MCPError`, so the sentence above is your traceback's last line, not the class name.
 
-The fix is the same for both: don't reach back mid-call. Move the question into a **resolver** (or return an `InputRequiredResult` yourself) and it becomes part of the *response*, which every connection can carry:
+For a `2026-07-28` client the fix is the same on all three: don't reach back mid-call. Move the question into a **resolver** (or return an `InputRequiredResult` yourself) and it becomes part of the *response*, which every connection can carry:
 
 ```python title="server.py" hl_lines="15-17 21"
 --8<-- "docs_src/troubleshooting/tutorial007.py"
 ```
 
-Same question, same `elicitation_callback` on the client. The difference is under the hood: a resolver lets the server *return* the question from the call instead of pushing it, so nothing ever flows server-to-client. **[Elicitation](handlers/elicitation.md)** covers resolvers; **[Multi-round-trip requests](handlers/multi-round-trip.md)** covers what happens on the wire.
+Same question, same `elicitation_callback` on the client. The difference is under the hood: a resolver lets the server *return* the question from the call instead of pushing it, so nothing ever flows server-to-client. That rescues every `2026-07-28` client, whichever of the three configurations the server is in. A *legacy* client is not rescued by the rewrite alone: `2025-11-25` has no way to return a question, so on a legacy connection the resolver still sends `elicitation/create` down the request-scoped channel, and still needs a server that keeps it — neither `stateless_http=True` nor `json_response=True`. **[Elicitation](handlers/elicitation.md)** covers resolvers; **[Multi-round-trip requests](handlers/multi-round-trip.md)** covers what happens on the wire.
 
 !!! check
     The tool with `ctx.elicit()` is not wrong, it is *pre-2026*. Connect with `mode="legacy"`
-    (the classic `initialize` handshake, spec `2025-11-25` and earlier) to a server that is not
-    `stateless_http=True`, and it works, because the server-to-client channel exists there.
+    (the classic `initialize` handshake, spec `2025-11-25` and earlier) to a server that is neither
+    `stateless_http=True` nor `json_response=True`, and it works, because the server-to-client
+    channel exists there.
     **[Protocol versions](protocol-versions.md)** is the page on what each version has.
 
 ## `MCPError: Invalid or expired requestState`
@@ -407,6 +410,6 @@ mcp = MCPServer("Weather", request_state_security=RequestStateSecurity(keys=[key
 * One 421, three spellings: `Server returned an error response` (the python `Client`), `421 Misdirected Request` / `Invalid Host header` (everything else), `Invalid Host header: <host>` (the server log). Fix: `transport_security=TransportSecuritySettings(allowed_hosts=[...])`.
 * `Task group is not initialized` -> a mounted app whose host lifespan never entered `mcp.session_manager.run()`.
 * `Session not found` -> the server restarted; reconnect.
-* `Cannot send 'elicitation/create': ... no back-channel ...` -> `ctx.elicit()` needs a server-to-client channel: a `2026-07-28` connection never has one, and `stateless_http=True` takes away the legacy one. Use a resolver. Its neighbour `Method not found` is a request for a method the other side's protocol revision doesn't have.
+* `Cannot send 'elicitation/create': ... no back-channel ...` -> `ctx.elicit()` needs a server-to-client channel: a `2026-07-28` connection never has one, `stateless_http=True` takes away the legacy one, and `json_response=True` takes away the request-scoped one. Use a resolver (a legacy client also needs a server that keeps the channel). Its neighbour `Method not found` is a request for a method the other side's protocol revision doesn't have.
 * `Client did not declare the form elicitation capability ...` and `Elicitation not supported` -> the client is missing `elicitation_callback=`.
 * `Invalid or expired requestState` never says why on the wire. The server log does; `unknown key` means share `RequestStateSecurity(keys=[...])` across workers.

src/mcp/server/runner.py

@@ -15,7 +15,7 @@
 
 import contextvars
 import logging
-from collections.abc import AsyncIterator, Awaitable, Mapping
+from collections.abc import AsyncIterator, Awaitable, Callable, Mapping
 from contextlib import asynccontextmanager
 from dataclasses import KW_ONLY, dataclass, replace
 from functools import cached_property, partial
@@ -473,6 +473,7 @@ async def serve_loop(
     session_id: str | None = None,
     init_options: InitializationOptions | None = None,
     raise_exceptions: bool = False,
+    transport_builder: Callable[[MessageMetadata], TransportContext] | None = None,
 ) -> None:
     """Drive ``server`` in handshake-only loop mode over a stream pair until the channel closes.
 
@@ -482,10 +483,20 @@ async def serve_loop(
     this; `Server.run` drives `serve_dual_era_loop`, which extends the same
     dispatcher recipe (notably the `inline_methods={"initialize"}` rule) with
     era routing.
+
+    Args:
+        transport_builder: Builds each inbound message's `TransportContext` from
+            its `SessionMessage.metadata`. Omitted, every message reads as a full
+            duplex pipe (`can_send_request=True`) - the truth for a plain stream
+            pair; a transport whose response cannot carry a server-initiated
+            request (streamable HTTP in JSON-response mode) passes its own
+            `StreamableHTTPServerTransport.transport_context_for` so the
+            request-scoped channel refuses instead of stalling.
     """
     dispatcher: JSONRPCDispatcher[TransportContext] = JSONRPCDispatcher(
         read_stream,
         write_stream,
+        transport_builder=transport_builder,
         raise_handler_exceptions=raise_exceptions,
         # Handle `initialize` inline so a client that pipelines it with the
         # next request (spec: SHOULD NOT, not MUST NOT) sees the initialized

src/mcp/server/streamable_http.py

@@ -44,7 +44,8 @@
 from mcp.shared._context_streams import ContextReceiveStream, ContextSendStream, create_context_streams
 from mcp.shared._stream_protocols import ReadStream, WriteStream
 from mcp.shared.inbound import MCP_PROTOCOL_VERSION_HEADER
-from mcp.shared.message import ServerMessageMetadata, SessionMessage
+from mcp.shared.message import MessageMetadata, ServerMessageMetadata, SessionMessage
+from mcp.shared.transport_context import TransportContext
 
 logger = logging.getLogger(__name__)
 
@@ -166,8 +167,13 @@ def __init__(
         Args:
             mcp_session_id: Optional session identifier for this connection.
                             Must contain only visible ASCII characters (0x21-0x7E).
-            is_json_response_enabled: If True, return JSON responses for requests
-                                    instead of SSE streams. Default is False.
+            is_json_response_enabled: If True, answer each request POST with a single
+                                    JSON body instead of an SSE stream. The body carries
+                                    only the response, so `transport_context_for` reports
+                                    `can_send_request=False` for it: a server-initiated
+                                    request on the request-scoped channel raises
+                                    `NoBackChannelError` and request-scoped notifications
+                                    are dropped. Default is False.
             event_store: Event store for resumability support. If provided,
                         resumability will be enabled, allowing clients to
                         reconnect and resume messages.
@@ -205,6 +211,25 @@ def is_terminated(self) -> bool:
         """Check if this transport has been explicitly terminated."""
         return self._terminated
 
+    def transport_context_for(self, metadata: MessageMetadata) -> TransportContext:
+        """Build the `TransportContext` for an inbound message this transport delivered.
+
+        The transport owns what a request's response can carry, so it supplies
+        the loop dispatcher's `transport_builder`. A JSON body holds exactly one
+        JSON-RPC response, so in JSON-response mode the request-scoped channel has
+        no room for a server-initiated request and `can_send_request` is `False`:
+        `ctx.elicit()` raises `NoBackChannelError` at once instead of parking a
+        waiter no reply can reach. An SSE response streams whatever the handler
+        emits. The connection's standalone GET stream is a separate channel and
+        is not described here.
+        """
+        request = metadata.request_context if isinstance(metadata, ServerMessageMetadata) else None
+        return TransportContext(
+            kind="streamable-http",
+            can_send_request=not self.is_json_response_enabled,
+            headers=request.headers if isinstance(request, Request) else None,
+        )
+
     def close_sse_stream(self, request_id: RequestId) -> None:
         """Close SSE connection for a specific request without terminating the stream.
 

src/mcp/server/streamable_http_manager.py

@@ -6,6 +6,7 @@
 import logging
 from collections import deque
 from collections.abc import AsyncIterator
+from dataclasses import replace
 from typing import TYPE_CHECKING, Any, Final
 from uuid import uuid4
 
@@ -214,12 +215,14 @@ async def run_stateless_server(*, task_status: TaskStatus[None] = anyio.TASK_STA
                     read_stream,
                     write_stream,
                     inline_methods=frozenset({"initialize"}),
-                    # No session ID means a server-to-client request can be
-                    # written to this POST's response stream, but the client's
-                    # reply has nowhere to land — `can_send_request=False`
-                    # makes the per-request channel raise `NoBackChannelError`
-                    # for requests while still allowing notifications.
-                    transport_builder=lambda _md: TransportContext(kind="streamable-http", can_send_request=False),
+                    # The transport says what its response stream can carry; on
+                    # top of that, no session ID means the client's reply to a
+                    # server request has nowhere to land, so the request-scoped
+                    # channel refuses (`NoBackChannelError`) even in SSE mode
+                    # while still forwarding notifications.
+                    transport_builder=lambda md: replace(
+                        http_transport.transport_context_for(md), can_send_request=False
+                    ),
                 )
                 # Born-ready, no standalone channel: the legacy stateless path
                 # never opens a GET stream and need not see `initialize`. The
@@ -320,13 +323,15 @@ async def run_server(*, task_status: TaskStatus[None] = anyio.TASK_STATUS_IGNORE
                             with idle_scope:
                                 # Drive via `serve_loop` (not `Server.run()`) so the
                                 # manager's already-entered lifespan is reused
-                                # rather than re-entered per session.
+                                # rather than re-entered per session; the transport
+                                # rules on what each request's response can carry.
                                 await serve_loop(
                                     self.app,
                                     read_stream,
                                     write_stream,
                                     lifespan_state=self._lifespan_state,
                                     session_id=http_transport.mcp_session_id,
+                                    transport_builder=http_transport.transport_context_for,
                                 )
 
                             if idle_scope.cancelled_caught: