Harden the experimental modern HTTP entry's error and cleanup paths

- Parse-error response keeps the required "id": null member
- 405 carries the Allow: POST header
- exit_stack.aclose() is shielded, bounded, and exception-suppressed,
  matching ServerRunner.run()'s contract
- The success/error response is sent inside the per-request lifespan
  scope so a teardown error cannot drop an already-computed result
- Coverage tests for the cleanup-raises and cleanup-hangs arms
- Two no-branch pragmas for the 3.14 nested-async-with coverage quirk

Claude-Session: https://claude.ai/code/session_017S3aJaxEHeMvftp6whnHWK

Author: maxisbey

src/mcp/server/_experimental/streamable_http_modern.py

@@ -24,7 +24,11 @@
 from starlette.responses import Response
 from starlette.types import Receive, Scope, Send
 
-from mcp.server.runner import ServerRunner, otel_middleware
+from mcp.server.runner import (
+    _EXIT_STACK_CLOSE_TIMEOUT,  # type: ignore[reportPrivateUsage]
+    ServerRunner,
+    otel_middleware,
+)
 from mcp.server.transport_security import TransportSecurityMiddleware, TransportSecuritySettings
 from mcp.shared.dispatcher import CallOptions, OnNotify, OnRequest
 from mcp.shared.exceptions import MCPError, NoBackChannelError
@@ -180,7 +184,7 @@ async def handle_modern_request(
 
     if request.method != "POST":
         # TODO: GET/DELETE rejection (405 + -32601) lands with the validation ladder.
-        await Response(status_code=405)(scope, receive, send)
+        await Response(status_code=405, headers={"Allow": "POST"})(scope, receive, send)
         return
 
     body = await request.body()
@@ -189,7 +193,7 @@ async def handle_modern_request(
     except ValidationError:
         msg = JSONRPCError(jsonrpc="2.0", id=None, error=ErrorData(code=PARSE_ERROR, message="Parse error"))
         await Response(
-            msg.model_dump_json(by_alias=True, exclude_none=True),
+            msg.model_dump_json(by_alias=True),
             status_code=400,
             media_type="application/json",
         )(scope, receive, send)
@@ -210,11 +214,20 @@ async def handle_modern_request(
         try:
             msg = await dispatcher.handle(req, runner._compose_on_request())  # type: ignore[reportPrivateUsage]
         finally:
-            await runner.connection.exit_stack.aclose()
-
-    # TODO: error.code -> HTTP status mapping is a follow-up; 200 for all JSONRPCError bodies for now.
-    await Response(
-        msg.model_dump_json(by_alias=True, exclude_none=True),
-        status_code=200,
-        media_type="application/json",
-    )(scope, receive, send)
+            with anyio.move_on_after(_EXIT_STACK_CLOSE_TIMEOUT, shield=True) as cancel_scope:
+                try:
+                    await runner.connection.exit_stack.aclose()
+                except Exception:
+                    logger.exception("connection exit_stack cleanup raised")
+            if cancel_scope.cancelled_caught:
+                logger.warning(
+                    "connection exit_stack cleanup exceeded %s seconds; abandoning remaining callbacks",
+                    _EXIT_STACK_CLOSE_TIMEOUT,
+                )
+
+        # TODO: error.code -> HTTP status mapping is a follow-up; 200 for all JSONRPCError bodies for now.
+        await Response(
+            msg.model_dump_json(by_alias=True, exclude_none=True),
+            status_code=200,
+            media_type="application/json",
+        )(scope, receive, send)

tests/interaction/lowlevel/test_lifecycle_stateless.py

@@ -102,15 +102,15 @@ async def test_initialize_on_a_pinned_session_is_rejected_before_any_frame_is_se
     async with create_client_server_memory_streams() as ((client_read, client_write), (server_read, _server_write)):
         async with ClientSession(client_read, client_write, protocol_version="2026-07-28") as session:
             with anyio.fail_after(5):
-                with pytest.raises(RuntimeError) as exc_info:
+                with pytest.raises(RuntimeError) as exc_info:  # pragma: no branch
                     await session.initialize()
         assert str(exc_info.value) == snapshot(
             "initialize() must not be called on a session pinned to a stateless protocol version"
         )
         # Nothing left the client: closing the sender turns an empty buffer into EndOfStream.
         await client_write.aclose()
         with anyio.fail_after(5):
-            with pytest.raises(anyio.EndOfStream):
+            with pytest.raises(anyio.EndOfStream):  # pragma: no branch
                 await server_read.receive()
 
 

tests/server/test_experimental_streamable_http_modern.py

@@ -6,15 +6,18 @@
 mapping in ``handle()``, and the request-validation ladder in ``handle_modern_request``.
 """
 
+import logging
 from collections.abc import Mapping
 from typing import Any
 
+import anyio
 import httpx
 import pytest
 from starlette.requests import Request
 from starlette.types import Receive, Scope, Send
 
-from mcp.server import Server
+import mcp.server._experimental.streamable_http_modern as modern
+from mcp.server import Server, ServerRequestContext
 from mcp.server._experimental.streamable_http_modern import (
     SingleExchangeDispatcher,
     _SingleExchangeDispatchContext,
@@ -24,7 +27,7 @@
 from mcp.shared.dispatcher import DispatchContext
 from mcp.shared.exceptions import NoBackChannelError
 from mcp.shared.transport_context import TransportContext
-from mcp.types import INVALID_PARAMS, PARSE_ERROR, JSONRPCError, JSONRPCRequest
+from mcp.types import INVALID_PARAMS, PARSE_ERROR, JSONRPCError, JSONRPCRequest, ListToolsResult, PaginatedRequestParams
 
 pytestmark = pytest.mark.anyio
 
@@ -98,6 +101,7 @@ async def test_handle_modern_request_rejects_non_post_with_405() -> None:
     async with _asgi_client(Server("test")) as http:
         response = await http.get("/mcp")
     assert response.status_code == 405
+    assert response.headers["allow"] == "POST"
 
 
 async def test_handle_modern_request_rejects_malformed_body_with_parse_error() -> None:
@@ -106,7 +110,11 @@ async def test_handle_modern_request_rejects_malformed_body_with_parse_error() -
         response = await http.post("/mcp", content=b"not json", headers={"content-type": "application/json"})
     assert response.status_code == 400
     assert response.headers["content-type"].split(";", 1)[0] == "application/json"
-    assert response.json() == {"jsonrpc": "2.0", "error": {"code": PARSE_ERROR, "message": "Parse error"}}
+    assert response.json() == {
+        "jsonrpc": "2.0",
+        "id": None,
+        "error": {"code": PARSE_ERROR, "message": "Parse error", "data": None},
+    }
 
 
 async def test_handle_modern_request_returns_transport_security_error_response() -> None:
@@ -116,3 +124,66 @@ async def test_handle_modern_request_returns_transport_security_error_response()
         response = await http.post("/mcp", json={}, headers={"content-type": "application/json"})
     assert response.status_code == 421
     assert response.text == "Invalid Host header"
+
+
+def _list_tools_body() -> dict[str, Any]:
+    """A minimal valid 2026-07-28 ``tools/list`` request body, including the required ``_meta`` envelope."""
+    meta = {
+        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
+        "io.modelcontextprotocol/clientInfo": {"name": "raw", "version": "0.0.0"},
+        "io.modelcontextprotocol/clientCapabilities": {},
+    }
+    return {"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {"_meta": meta}}
+
+
+async def test_handle_modern_request_sends_response_when_exit_stack_cleanup_raises(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """A raising ``connection.exit_stack`` callback is logged and swallowed; the computed result still ships.
+
+    The exit-stack guard mirrors ``ServerRunner.run``: cleanup runs in a ``finally`` after the
+    handler, and an exception there must not displace the JSON-RPC response that was already built.
+    """
+
+    async def boom() -> None:
+        raise RuntimeError("cleanup failed")
+
+    async def list_tools(ctx: ServerRequestContext, params: PaginatedRequestParams | None) -> ListToolsResult:
+        ctx.session._connection.exit_stack.push_async_callback(boom)
+        return ListToolsResult(tools=[], ttl_ms=0, cache_scope="public")
+
+    with caplog.at_level(logging.ERROR, logger=modern.__name__):
+        async with _asgi_client(Server("test", on_list_tools=list_tools)) as http:
+            response = await http.post("/mcp", json=_list_tools_body(), headers={"content-type": "application/json"})
+
+    assert response.status_code == 200
+    assert response.json()["result"]["tools"] == []
+    assert "connection exit_stack cleanup raised" in caplog.text
+
+
+async def test_handle_modern_request_sends_response_when_exit_stack_cleanup_hangs(
+    monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
+) -> None:
+    """A blocking ``connection.exit_stack`` callback is abandoned at the grace deadline; the response still ships.
+
+    Grace patched to 0 so the deadline is already expired on entry: the bounded unwind cancels the
+    blocker at its first checkpoint, the abandonment warning is logged, and the JSON-RPC response
+    that was built before cleanup is sent unchanged.
+    """
+    monkeypatch.setattr(modern, "_EXIT_STACK_CLOSE_TIMEOUT", 0)
+
+    async def block() -> None:
+        await anyio.Event().wait()
+        raise AssertionError("unreachable")  # pragma: no cover
+
+    async def list_tools(ctx: ServerRequestContext, params: PaginatedRequestParams | None) -> ListToolsResult:
+        ctx.session._connection.exit_stack.push_async_callback(block)
+        return ListToolsResult(tools=[], ttl_ms=0, cache_scope="public")
+
+    with anyio.fail_after(5), caplog.at_level(logging.WARNING, logger=modern.__name__):
+        async with _asgi_client(Server("test", on_list_tools=list_tools)) as http:
+            response = await http.post("/mcp", json=_list_tools_body(), headers={"content-type": "application/json"})
+
+    assert response.status_code == 200
+    assert response.json()["result"]["tools"] == []
+    assert "abandoning remaining callbacks" in caplog.text