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!

[maxisbey]

Thanks for the PR, and sorry it sat here without a proper review.

We're closing most of the open PR backlog. v2 is out and changed a lot of the SDK, so many older PRs no longer apply as written, and we're a small team that realistically doesn't have the capacity to work through the rest.

If this still matters to you on v2, the most useful thing you can do is open an issue (or comment on the existing one) with your use case and a repro. Hearing why it matters to you is what we use to decide what to prioritise.

_{AI Disclaimer}