fix(client/stdio): allow FIFO cleanup of multiple transports on asyncio (#577)

Approval required
SA
7mo ago
+272-30

Fixes #577.

The bug

stdio_client wraps its reader / writer in anyio.create_task_group() inside the async context manager body (src/mcp/client/stdio.py L180 on main). A task group binds its cancel scope to whichever task entered the generator, and anyio enforces a strict LIFO stack on those scopes within a single task.

If a caller opens two transports from the same task and then closes them in the order they were opened — a pattern that shows up in multi-client orchestrators, DI containers and pytest fixtures — teardown crashes with:

RuntimeError: Attempted to exit a cancel scope that isn't the current task's current cancel scope

(The traceback in #577 matches this exactly. I reproduced it locally against a freshly cloned main with a minimal repro that spawns two python -c ... subprocesses and closes them FIFO.)

This has been biting users for a year — hits asyncio callers using AsyncExitStack, pytest fixtures, custom multi-client managers (see the comment thread on #577 for the list). The recommended workaround until now was "always clean up LIFO", which pushes anyio's cancel-scope discipline onto every consumer of the SDK and breaks naturally with many real code-organisation patterns.

The fix

On asyncio we don't need a task group to spawn the reader / writer — asyncio.create_task is enough. The tasks then live outside any caller-bound cancel scope, so each transport is self-contained and the cleanup order of two transports no longer matters.

  • Backend is detected via sniffio.current_async_library() (already a transitive dependency of anyio).
  • The documented shutdown sequence (close stdin → wait for process with PROCESS_TERMINATION_TIMEOUT → escalate to _terminate_process_tree → close the memory streams) is lifted into a shared _cleanup_process_and_streams helper so the two branches can't drift.
  • Reader / writer cancellation happens after the process-level cleanup so late I/O errors surfaced during teardown are expected and swallowed, matching the pre-existing anyio.ClosedResourceError handling in those functions.
  • On structured-concurrency backends (trio) the anyio task group is kept — trio forbids orphan tasks by design, and cross-task cleanup is fundamentally incompatible with that model. Trio callers still have to clean up LIFO. This is acknowledged in the inline comment on the backend branch.

Tests

Three new regression tests in tests/client/test_stdio.py, all asyncio-only (parametrize(\"anyio_backend\", [\"asyncio\"])):

TestWhat it pins
test_stdio_client_supports_fifo_cleanup_on_asyncioThe exact scenario from #577 — two transports opened, closed FIFO. Verified to fail on the unmodified main branch with the original RuntimeError, so it is a real regression guard, not a tautology.
test_stdio_client_supports_lifo_cleanup_on_asyncioSanity: historical LIFO path must still work unchanged after the fix.
test_stdio_client_shared_exit_stack_fifo_on_asyncioA single AsyncExitStack around two transports (ExitStack already runs callbacks LIFO, so this case worked before — but worth pinning so a future refactor of the asyncio branch can't silently break it).

pytest tests/client/test_stdio.py --timeout=30 → 13 passed, 1 skipped (the Unix-only SIGINT test is the pre-existing skip; 10 other pre-existing tests + 3 new, none regressed).

Negative-path validation: stashed only src/mcp/client/stdio.py, reran the FIFO test — it fails with the original RuntimeError: Attempted to exit a cancel scope that isn't the current task's current cancel scope. Restored the fix, all three pass.

Scope

Kept strictly to stdio_client. sse.py, streamable_http.py, websocket.py use a similar task-group-in-generator pattern and may need the same treatment — they can be handled in follow-ups if this approach is acceptable.