fix(server): guard GET SSE response with CancelScope to prevent Windows deadlock (#2653)

[isheng-eqi]

Summary

Fixes #2653 — mcp.server.fastmcp.FastMCP HTTP transport deadlocks after ~5 sequential client sessions on Windows.

Root Cause

sse-starlette's EventSourceResponse.__call__ creates an internal anyio.TaskGroup whose child tasks (_ping, _listen_for_disconnect, _listen_for_exit_signal, standalone_sse_writer) may not respond to cancellation promptly on Windows ProactorEventLoop. When the client disconnects, orphan children remain parked in anyio.sleep() or Event.wait(), preventing TaskGroup.__aexit__ from completing.

The _handle_get_request handler directly awaits the EventSourceResponse callable, so the hung TaskGroup blocks the handler forever. Each session that opens a GET SSE stream and disconnects leaks one such hung task group. After enough sessions (~5–18 depending on Python version), the next initialize POST never dispatches and the server deadlocks.

The raw mcp.server.lowlevel.Server + StreamableHTTPSessionManager path is unaffected because it writes text/event-stream directly without sse-starlette. The Node.js reference server is also unaffected. The defect is confined to the FastMCP wrapper layer's use of sse-starlette.EventSourceResponse.

Fix

Three changes in src/mcp/server/streamable_http.py:

1. __init__: Add _active_get_response_scope: anyio.CancelScope | None attribute to track the in-flight GET SSE response.

2. _handle_get_request: Wrap the await response(...) call with the cancel scope instead of awaiting it directly. This gives terminate() a handle to force-cancel a hung response.

3. terminate(): Cancel _active_get_response_scope (if set) before closing streams. This breaks the sse-starlette TaskGroup deadlock and allows the session to clean up, even on Windows ProactorEventLoop.

The fix is minimal (19 insertions, 5 deletions), backward-compatible, and targets only the GET SSE path where EventSourceResponse is awaited directly. The POST handler already runs EventSourceResponse inside an anyio.create_task_group() which provides equivalent cancellation safety.

Related

• HTTP transport: orphan sse_starlette EventSourceResponse tasks accumulate per session, deadlocking after ~12 sequential client sessions on Windows PrefectHQ/fastmcp#4192 — full investigation, cross-control matrix, deterministic reproduction
• sse-starlette — issue is in the library's TaskGroup cleanup on Windows, but the SDK can defend against it here

[cubic-dev-ai]

1 issue found across 1 file

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[isheng-eqi]

Good catch. The single _active_get_response_scope does have a concurrent GET-start race — two in-flight SSE connections would leave the first without a cancellation handle.

Fixed in 3c0d47b: switched to set[CancelScope] so terminate() iterates and cancels all active scopes. Added scope: CancelScope | None = None guard + if scope is not None in the finally block for type safety.

[isheng-eqi]

Hi @maxisbey @felixweinberger, could you take a look at this PR when you have a moment?

This fixes #2653 — a Windows-specific deadlock in FastMCP SSE transport where sse-starlette TaskGroup children hang on ProactorEventLoop.

CI status: The fork CI is all green (isheng-eqi/python-sdk actions). The upstream CI checks show failure because the required workflow names don't match what runs on fork PRs — not a code issue.

Review: The cubic-dev-ai bot flagged a concurrent GET-start race on the initial commit. This was addressed in 3c0d47b by switching to set[CancelScope] so terminate() iterates and cancels all active scopes.

The fix is minimal (19 insertions, 5 deletions), backward-compatible, and targets only the FastMCP GET SSE path. The raw lowlevel.Server + StreamableHTTPSessionManager path is unaffected.

Thanks!