fix: bound the shielded exit-stack teardown in ServerRunner.run()

The exit_stack unwind after dispatcher.run() exits must stay shielded:
without the shield, outer cancellation (server shutdown, SHTTP idle
timeout) would skip per-connection cleanup registered by handlers and
middleware. But an unbounded shield means one misbehaving cleanup
callback that never returns wedges shutdown forever.

Replace the bare CancelScope(shield=True) with
move_on_after(_EXIT_STACK_CLOSE_TIMEOUT, shield=True) (5 seconds) so
well-behaved cleanup still runs to completion while a hung callback is
abandoned at the deadline. Log a warning when the grace period expires
so abandoned callbacks are visible rather than silent.

Author: maxisbey

src/mcp/server/runner.py

@@ -63,6 +63,13 @@
 
 _INIT_EXEMPT: frozenset[str] = frozenset({"ping"})
 
+_EXIT_STACK_CLOSE_TIMEOUT: float = 5
+"""Grace period in seconds for `connection.exit_stack` teardown in `run()`.
+
+The unwind is shielded from outer cancellation so per-connection cleanup runs
+even when the server is being torn down; the shield must be bounded or a
+misbehaving cleanup callback would hang shutdown indefinitely."""
+
 
 def _extract_meta(params: Mapping[str, Any] | None) -> RequestParamsMeta | None:
     """Lift `_meta` from raw params with the same key-aliasing pydantic applies.
@@ -194,13 +201,15 @@ async def run(self, *, task_status: anyio.abc.TaskStatus[None] = anyio.TASK_STAT
         to `dispatcher.run()`. `task_status.started()` is forwarded so callers
         can `await tg.start(runner.run)` and resume once the dispatcher is
         ready to accept requests. Once the dispatcher exits,
-        `connection.exit_stack` is unwound (shielded) so any per-connection
-        cleanup registered by handlers or middleware runs to completion.
+        `connection.exit_stack` is unwound (shielded from outer cancellation,
+        bounded by `_EXIT_STACK_CLOSE_TIMEOUT`) so any per-connection cleanup
+        registered by handlers or middleware gets a chance to run without a
+        misbehaving callback hanging shutdown indefinitely.
         """
         try:
             await self.dispatcher.run(self._compose_on_request(), self._on_notify, task_status=task_status)
         finally:
-            with anyio.CancelScope(shield=True):
+            with anyio.move_on_after(_EXIT_STACK_CLOSE_TIMEOUT, shield=True) as scope:
                 try:
                     await self.connection.exit_stack.aclose()
                 except Exception:
@@ -210,6 +219,11 @@ async def run(self, *, task_status: anyio.abc.TaskStatus[None] = anyio.TASK_STAT
                     # exception from `dispatcher.run()` (including the
                     # CancelledError that SHTTP idle-timeout teardown checks).
                     logger.exception("connection exit_stack cleanup raised")
+            if scope.cancelled_caught:
+                logger.warning(
+                    "connection exit_stack cleanup exceeded %s seconds; abandoning remaining callbacks",
+                    _EXIT_STACK_CLOSE_TIMEOUT,
+                )
 
     def _compose_on_request(self) -> OnRequest:
         """Wrap `_on_request` in `dispatch_middleware`, outermost-first.

tests/server/test_runner.py

@@ -14,6 +14,7 @@
 import pytest
 from opentelemetry.trace import SpanKind, StatusCode
 
+import mcp.server.runner
 from mcp.server.context import ServerRequestContext
 from mcp.server.lowlevel.server import NotificationOptions, Server
 from mcp.server.models import InitializationOptions
@@ -775,3 +776,55 @@ async def _boom() -> None:
         await client.send_raw_request("tools/list", None)
     assert cleaned == ["ok"]
     assert "connection exit_stack cleanup raised" in caplog.text
+
+
+@pytest.mark.anyio
+async def test_runner_exit_stack_blocking_cleanup_abandoned_after_grace(
+    server: SrvT, monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
+) -> None:
+    """A cleanup callback that never returns is abandoned once the grace period
+    elapses: `run()` exits, later callbacks in the unwind are cancelled at
+    their first checkpoint, and a warning is logged. Grace 0 means the deadline
+    is already expired on entry, so the abandonment is immediate."""
+    monkeypatch.setattr(mcp.server.runner, "_EXIT_STACK_CLOSE_TIMEOUT", 0)
+    ran: list[str] = []
+    release = anyio.Event()
+
+    async def _abandoned() -> None:
+        # LIFO unwind: pushed first, so it runs after the blocker. By then the
+        # deadline has fired, so this checkpoint raises and the append never runs.
+        await anyio.sleep(0)
+        ran.append("abandoned")
+
+    async def _blocker() -> None:
+        ran.append("blocker started")
+        await release.wait()
+        ran.append("blocker finished")
+
+    async with connected_runner(server) as (client, runner):
+        runner.connection.exit_stack.push_async_callback(_abandoned)
+        runner.connection.exit_stack.push_async_callback(_blocker)
+        await client.send_raw_request("tools/list", None)
+    assert ran == ["blocker started"]
+    assert "abandoning remaining callbacks" in caplog.text
+
+
+@pytest.mark.anyio
+async def test_runner_exit_stack_fast_cleanup_completes_within_grace(
+    server: SrvT, caplog: pytest.LogCaptureFixture
+) -> None:
+    """Well-behaved cleanup callbacks run to completion under the bounded
+    unwind and no abandonment warning is logged. Uses the production grace;
+    the deadline never delays a fast unwind, it only bounds a hung one."""
+    cleaned: list[int] = []
+
+    async def _append(i: int) -> None:
+        await anyio.sleep(0)
+        cleaned.append(i)
+
+    async with connected_runner(server) as (client, runner):
+        for i in (1, 2):
+            runner.connection.exit_stack.push_async_callback(_append, i)
+        await client.send_raw_request("tools/list", None)
+    assert cleaned == [2, 1]
+    assert "abandoning remaining callbacks" not in caplog.text