Transport: pre-session 404 maps to METHOD_NOT_FOUND; POSTs never read cached pv header. serve_one reshape + raise_exceptions

- Bare HTTP 404 before a session is established now maps to METHOD_NOT_FOUND
  (was INVALID_REQUEST/"Session terminated", which is meaningless pre-session);
  with a session_id, 404 keeps the session-terminated mapping
- _prepare_headers split: _base_headers (POST) vs _prepare_headers (GET/DELETE).
  POSTs never read the cached MCP-Protocol-Version header — they get it via
  per-message metadata only. Prevents the discover probe's header from leaking
  onto a fallback initialize POST.
- serve_one reshaped to (server, dctx, method, params, *, ..., raise_exceptions);
  modern_on_request drops the JSONRPCRequest round-trip and threads
  raise_exceptions through to to_jsonrpc_response(raise_unhandled=). Client's
  modern in-process branch now honors raise_exceptions (handler exceptions
  chain via __cause__ instead of being sanitized to INTERNAL_ERROR).

Author: maxisbey

src/mcp/client/client.py

@@ -159,7 +159,10 @@ async def __aenter__(self) -> Client:
                 client_disp, server_disp = create_direct_dispatcher_pair()
                 tg = await exit_stack.enter_async_context(anyio.create_task_group())
                 exit_stack.callback(server_disp.close)
-                await tg.start(server_disp.run, modern_on_request(self._inproc_server, lifespan_state), _drop_notify)
+                on_request = modern_on_request(
+                    self._inproc_server, lifespan_state, raise_exceptions=self.raise_exceptions
+                )
+                await tg.start(server_disp.run, on_request, _drop_notify)
                 session = ClientSession(
                     dispatcher=client_disp,
                     read_timeout_seconds=self.read_timeout_seconds,

src/mcp/client/streamable_http.py

@@ -23,6 +23,7 @@
 from mcp.types import (
     INTERNAL_ERROR,
     INVALID_REQUEST,
+    METHOD_NOT_FOUND,
     PARSE_ERROR,
     ErrorData,
     JSONRPCError,
@@ -84,19 +85,29 @@ def __init__(self, url: str) -> None:
         # GET/DELETE that don't carry per-message metadata.
         self._protocol_version_header: str | None = None
 
-    def _prepare_headers(self) -> dict[str, str]:
-        """Build MCP-specific request headers.
+    def _base_headers(self) -> dict[str, str]:
+        """Build MCP-specific request headers (accept / content-type / session-id).
 
         These headers will be merged with the httpx.AsyncClient's default headers,
-        with these MCP-specific headers taking precedence.
+        with these MCP-specific headers taking precedence. POSTs use this directly:
+        their protocol-version header arrives per-message via ``metadata.headers``,
+        so they must never read the cached value.
         """
         headers: dict[str, str] = {
             "accept": "application/json, text/event-stream",
             "content-type": "application/json",
         }
-        # Add session headers if available
         if self.session_id:
             headers[MCP_SESSION_ID] = self.session_id
+        return headers
+
+    def _prepare_headers(self) -> dict[str, str]:
+        """Base headers plus the cached protocol-version header.
+
+        Used by transport-internal GET/DELETE (listen stream, resumption,
+        reconnect, terminate) which don't carry per-message metadata.
+        """
+        headers = self._base_headers()
         if self._protocol_version_header:
             headers[MCP_PROTOCOL_VERSION_HEADER] = self._protocol_version_header
         return headers
@@ -238,7 +249,7 @@ async def _handle_resumption_request(self, ctx: RequestContext) -> None:
 
     async def _handle_post_request(self, ctx: RequestContext) -> None:
         """Handle a POST request with response processing."""
-        headers = self._prepare_headers()
+        headers = self._base_headers()
         message = ctx.session_message.message
         if ctx.metadata is not None and ctx.metadata.headers is not None:
             headers.update(ctx.metadata.headers)
@@ -276,7 +287,13 @@ async def _handle_post_request(self, ctx: RequestContext) -> None:
                             pass
                         logger.debug("Non-2xx body was not a JSON-RPC error; using fallback")
                     if response.status_code == 404:
-                        error_data = ErrorData(code=INVALID_REQUEST, message="Session terminated")
+                        if self.session_id is None:
+                            # No session yet → 404 is the HTTP-level spelling of
+                            # METHOD_NOT_FOUND (gateway / legacy server doesn't know
+                            # this method); "Session terminated" would be a lie here.
+                            error_data = ErrorData(code=METHOD_NOT_FOUND, message="Not Found")
+                        else:
+                            error_data = ErrorData(code=INVALID_REQUEST, message="Session terminated")
                     else:
                         error_data = ErrorData(code=INTERNAL_ERROR, message="Server returned an error response")
                     session_message = SessionMessage(JSONRPCError(jsonrpc="2.0", id=message.id, error=error_data))

src/mcp/server/_streamable_http_modern.py

@@ -193,5 +193,5 @@ async def handle_modern_request(
         request_id=req.id,
         message_metadata=ServerMessageMetadata(request_context=request),
     )
-    msg = await serve_one(app, req, connection=connection, dctx=dctx, lifespan_state=lifespan_state)
+    msg = await serve_one(app, dctx, req.method, req.params, connection=connection, lifespan_state=lifespan_state)
     await _write(msg, scope, receive, send)

src/mcp/server/runner.py

@@ -49,7 +49,6 @@
     InitializeRequestParams,
     InitializeResult,
     JSONRPCError,
-    JSONRPCRequest,
     JSONRPCResponse,
     RequestId,
     RequestParams,
@@ -183,20 +182,26 @@ async def aclose_shielded(connection: Connection) -> None:
         )
 
 
-async def to_jsonrpc_response(request_id: RequestId, coro: Awaitable[dict[str, Any]]) -> JSONRPCResponse | JSONRPCError:
+async def to_jsonrpc_response(
+    request_id: RequestId, coro: Awaitable[dict[str, Any]], *, raise_unhandled: bool = False
+) -> JSONRPCResponse | JSONRPCError:
     """Await ``coro`` and wrap its outcome as the JSON-RPC reply for ``request_id``.
 
     The exception-to-wire boundary for the request-per-call drivers
     (`serve_one`, the modern HTTP entry). `MCPError` and `ValidationError`
     map via the shared `handler_exception_to_error_data` ladder; any other
     exception is logged and surfaced as `INTERNAL_ERROR` so handler internals
-    never reach the wire.
+    never reach the wire. Set ``raise_unhandled`` to let unmapped exceptions
+    propagate instead of being sanitized — used by the in-process test path so
+    handler tracebacks reach the caller.
     """
     try:
         result = await coro
     except Exception as exc:
         error = handler_exception_to_error_data(exc)
         if error is None:
+            if raise_unhandled:
+                raise
             logger.exception("request handler raised")
             error = ErrorData(code=INTERNAL_ERROR, message="Internal server error")
         return JSONRPCError(jsonrpc="2.0", id=request_id, error=error)
@@ -497,34 +502,45 @@ async def serve_loop(
 
 async def serve_one(
     server: Server[LifespanT],
-    request: JSONRPCRequest,
+    dctx: DispatchContext[TransportContext],
+    method: str,
+    params: Mapping[str, Any] | None,
     *,
     connection: Connection,
-    dctx: DispatchContext[TransportContext],
     lifespan_state: LifespanT,
+    raise_exceptions: bool = False,
 ) -> JSONRPCResponse | JSONRPCError:
-    """Handle a single ``request`` and return its JSON-RPC reply.
-
-    The single-exchange driver: builds the kernel, runs `on_request` once for
-    `request` under `dctx`, maps the outcome to a `JSONRPCResponse` /
-    `JSONRPCError` via `to_jsonrpc_response`, and tears down
-    `connection.exit_stack` (shielded) on the way out. The entry constructs
-    the (born-ready) `Connection` and the `dctx`; this only consumes them.
+    """Handle a single request ``(method, params)`` and return its JSON-RPC reply.
+
+    The single-exchange driver: builds the kernel, runs `on_request` once under
+    `dctx`, maps the outcome to a `JSONRPCResponse` / `JSONRPCError` via
+    `to_jsonrpc_response`, and tears down `connection.exit_stack` (shielded) on
+    the way out. The entry constructs the (born-ready) `Connection` and the
+    `dctx`; this only consumes them. ``raise_exceptions`` lets unmapped handler
+    exceptions propagate instead of being sanitized to `INTERNAL_ERROR`.
     """
     runner = ServerRunner(server, connection, lifespan_state)
     try:
-        return await to_jsonrpc_response(request.id, runner.on_request(dctx, request.method, request.params))
+        # Single-exchange driver only handles requests; both entries populate `request_id`.
+        # TODO(L54): drop once `DispatchContext` is split so `OnRequest` carries a non-Optional id.
+        assert dctx.request_id is not None
+        return await to_jsonrpc_response(
+            dctx.request_id, runner.on_request(dctx, method, params), raise_unhandled=raise_exceptions
+        )
     finally:
         await aclose_shielded(connection)
 
 
-def modern_on_request(server: Server[LifespanT], lifespan_state: LifespanT) -> OnRequest:
+def modern_on_request(
+    server: Server[LifespanT], lifespan_state: LifespanT, *, raise_exceptions: bool = False
+) -> OnRequest:
     """Return an `OnRequest` callback that serves each call via `serve_one` with a fresh per-request `Connection`.
 
     Wire this into the server side of a `DirectDispatcher` peer-pair to drive an
     in-process server on the modern per-request-envelope path (each request
     carries protocol version, client info, and capabilities in `params._meta`;
-    no `initialize` handshake).
+    no `initialize` handshake). ``raise_exceptions`` lets unmapped handler
+    exceptions propagate to the caller for debuggable in-process testing.
     """
 
     async def handle(
@@ -536,12 +552,15 @@ async def handle(
             meta.get(CLIENT_INFO_META_KEY),
             meta.get(CLIENT_CAPABILITIES_META_KEY),
         )
-        # `OnRequest` is invoked for requests only, so `request_id` is always set.
-        assert dctx.request_id is not None
-        req = JSONRPCRequest(
-            jsonrpc="2.0", id=dctx.request_id, method=method, params=dict(params) if params is not None else None
+        msg = await serve_one(
+            server,
+            dctx,
+            method,
+            params,
+            connection=connection,
+            lifespan_state=lifespan_state,
+            raise_exceptions=raise_exceptions,
         )
-        msg = await serve_one(server, req, connection=connection, dctx=dctx, lifespan_state=lifespan_state)
         if isinstance(msg, JSONRPCError):
             raise MCPError(code=msg.error.code, message=msg.error.message, data=msg.error.data)
         return msg.result

tests/client/test_client.py

@@ -203,6 +203,23 @@ async def handle_read_resource(
         assert exc_info.value.error.code == 404
 
 
+async def test_raise_exceptions_propagates_handler_error_on_modern_inproc_path():
+    """`raise_exceptions=True` on the modern in-process path: an unmapped handler
+    exception reaches the client with its original type chained, instead of being
+    sanitized to an opaque `INTERNAL_ERROR`."""
+
+    async def handle_call_tool(ctx: ServerRequestContext, params: types.CallToolRequestParams) -> CallToolResult:
+        raise ValueError("boom")
+
+    server = Server("test", on_call_tool=handle_call_tool)
+    async with Client(server, mode="2026-07-28", raise_exceptions=True) as client:
+        with pytest.raises(MCPError) as exc_info:
+            await client.call_tool("explode", {})
+    # The original exception is chained — not swallowed into a generic "Internal server error".
+    assert isinstance(exc_info.value.__cause__, ValueError)
+    assert str(exc_info.value.__cause__) == "boom"
+
+
 async def test_get_prompt(app: MCPServer):
     """Test getting a prompt."""
     async with Client(app) as client:

tests/client/test_notification_response.py

@@ -204,12 +204,19 @@ async def test_invalid_json_response_sends_jsonrpc_error() -> None:
 
 
 def _create_non_2xx_json_body_app(status: int, body: bytes) -> Starlette:
-    """Server that returns a fixed non-2xx status + ``application/json`` body for non-init requests."""
+    """Server that returns a fixed non-2xx status + ``application/json`` body for non-init requests.
+
+    The initialize response carries an ``mcp-session-id`` so the client treats subsequent
+    requests as part of an established session (needed for the 404 → session-terminated mapping).
+    """
 
     async def handle_mcp_request(request: Request) -> Response:
         data = json.loads(await request.body())
         if data.get("method") == "initialize":
-            return _init_json_response(data)
+            return JSONResponse(
+                {"jsonrpc": "2.0", "id": data["id"], "result": INIT_RESPONSE},
+                headers={"mcp-session-id": "test-session"},
+            )
         if "id" not in data:
             return Response(status_code=202)
         return Response(content=body, status_code=status, media_type="application/json")

tests/client/test_streamable_http.py

@@ -15,9 +15,9 @@
 from inline_snapshot import snapshot
 
 from mcp.client.streamable_http import streamable_http_client
-from mcp.shared.inbound import encode_header_value
+from mcp.shared.inbound import MCP_PROTOCOL_VERSION_HEADER, encode_header_value
 from mcp.shared.message import ClientMessageMetadata, SessionMessage
-from mcp.types import JSONRPCRequest
+from mcp.types import METHOD_NOT_FOUND, JSONRPCError, JSONRPCRequest
 
 
 @pytest.mark.parametrize(
@@ -78,3 +78,61 @@ def handler(request: httpx.Request) -> httpx.Response:
     assert isinstance(reply, SessionMessage)
     assert [r.method for r in recorded] == ["POST"]
     assert recorded[0].headers["x-test"] == "v"
+
+
+@pytest.mark.anyio
+async def test_pre_session_bare_404_maps_to_method_not_found() -> None:
+    """A bare HTTP 404 (no JSON-RPC body) before any session-id is held maps to METHOD_NOT_FOUND.
+
+    Gateways and legacy servers 404 at the HTTP layer for unknown methods; with no session yet,
+    "Session terminated" is meaningless, and the discover→initialize fallback ladder keys on -32601.
+    """
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(404)
+
+    with anyio.fail_after(5):
+        async with (
+            httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http,
+            streamable_http_client("http://test/mcp", http_client=http) as (read, write),
+        ):
+            await write.send(SessionMessage(JSONRPCRequest(jsonrpc="2.0", id=1, method="server/discover", params={})))
+            reply = await read.receive()
+    assert isinstance(reply, SessionMessage)
+    assert isinstance(reply.message, JSONRPCError)
+    assert reply.message.error.code == METHOD_NOT_FOUND
+
+
+@pytest.mark.anyio
+async def test_post_does_not_read_cached_protocol_version_header() -> None:
+    """A POST's protocol-version header comes only from its own ``metadata.headers``.
+
+    The first POST carries (and caches) a pv header; the second POST sends no metadata
+    and must therefore carry no pv header — a stale cached value would poison the
+    fallback ``initialize`` after a failed discover probe. The cache exists for
+    transport-internal GET/DELETE only.
+    """
+    recorded: list[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        recorded.append(request)
+        body = json.loads(request.content)
+        return httpx.Response(200, json={"jsonrpc": "2.0", "id": body["id"], "result": {}})
+
+    with anyio.fail_after(5):
+        async with (
+            httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http,
+            streamable_http_client("http://test/mcp", http_client=http) as (read, write),
+        ):
+            await write.send(
+                SessionMessage(
+                    message=JSONRPCRequest(jsonrpc="2.0", id=1, method="server/discover", params={}),
+                    metadata=ClientMessageMetadata(headers={MCP_PROTOCOL_VERSION_HEADER: "2026-07-28"}),
+                )
+            )
+            await read.receive()
+            await write.send(SessionMessage(JSONRPCRequest(jsonrpc="2.0", id=2, method="initialize", params={})))
+            await read.receive()
+    assert [r.method for r in recorded] == ["POST", "POST"]
+    assert recorded[0].headers[MCP_PROTOCOL_VERSION_HEADER] == "2026-07-28"
+    assert MCP_PROTOCOL_VERSION_HEADER not in recorded[1].headers