Skip to content

fix(stdio): drain responses and bound stdout shutdown after EOF - #2680

Open
Epochex wants to merge 10 commits into
modelcontextprotocol:mainfrom
Epochex:fix/2678-stdio-drain-writes
Open

Epochex wants to merge 10 commits into
modelcontextprotocol:mainfrom
Epochex:fix/2678-stdio-drain-writes

Conversation

@Epochex

@Epochex Epochex commented May 25, 2026 •

Copy link
Copy Markdown

Fixes #2678. Also addresses the unread-stdout shutdown case tracked in #3674.

Closing stdin can mean the client has finished sending requests while it still expects responses on stdout. Allow accepted handlers to finish after read EOF, with a configurable handler drain window (one second by default).

The stdio transport now has a separate one-second output drain after the session returns. Stdout writes run in one daemon thread, with one response outstanding, so a full unread pipe cannot strand a non-daemon AnyIO file worker at interpreter shutdown. Process stdout uses a private raw descriptor, handles short writes, and avoids buffered-output finalization locks. A separate writer descriptor also prevents Windows CRT writes from blocking descriptor restoration. An abandoned default writer retains its stdout claim until it finishes; caller-supplied streams remain caller-owned.

These are separate drain budgets, not a single process-shutdown deadline. A response that cannot be written before the transport deadline may be abandoned. Write failures such as BrokenPipeError still propagate. The docs describe these semantics and the caller's responsibility for custom output streams.

Regression coverage includes real subprocesses with unread, drained, closed, degraded-isolation and explicitly supplied process stdout, plus blocked write/flush operations, write errors, partial writes and transport reuse after an abandoned write.

Validation with frozen dependencies (AnyIO 4.10.0):

  • Linux / Python 3.11: scripts/test — 5600 passed, 8 skipped, 1 xfailed; 100% statement/branch coverage; strict-no-cover passed.
  • Linux / Python 3.10: focused stdio/cancellation suite — 36 passed.
  • Windows / Python 3.13: focused suite — 35 passed, 1 skipped.
  • Ruff check/format and changed-file Pyright passed.
  • Full Windows pytest still has the same 63 failures and 4 errors as the original head; failure node IDs were compared against an unmodified checkout. Full Linux Pyright has the same 21 diagnostics as that baseline. These unrelated failures are not included in this fix.

AI assistance was used for implementation, review and testing.

@StantonMatt StantonMatt left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I ran this locally against the branch. The focused stdio/cancel tests pass:

TMPDIR=.codex-tmp/tmp UV_CACHE_DIR=.codex-tmp/uv-cache uv run --frozen pytest tests/server/test_cancel_handling.py tests/server/test_stdio.py -q

One shutdown edge looks worth tightening before merge. With drain_on_read_close=True, stdin EOF now waits for in-flight handlers to finish, but there is no bounded drain window. In a local memory-stream probe, I started a tools/call handler that does await anyio.sleep_forever(), sent initialize / notifications/initialized / tools/call, closed the input stream, and then waited for server.run(..., drain_on_read_close=True) to return. It did not return before anyio.fail_after(0.75).

That leaves redirected-stdin callers with the opposite failure mode: the previous branch can drop a response, while this one can keep the process alive forever if an accepted tool hangs after EOF. I think the drain path needs a small timeout or cancellation window so already-started handlers get a chance to flush, but EOF still remains a bounded shutdown signal.

@StantonMatt

This comment was marked as spam.

@StantonMatt StantonMatt left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new read_eof_drain_timeout_seconds path addresses the bounded-shutdown concern I raised.

I re-ran the focused stdio/cancel suite on head 721dd43:

TMPDIR=.codex-tmp/tmp UV_CACHE_DIR=.codex-tmp/uv-cache uv run --frozen pytest tests/server/test_cancel_handling.py tests/server/test_stdio.py -q

That passed with 9 passed, including test_server_bounds_drain_on_read_eof_when_handler_never_finishes. git diff --check origin/main...HEAD is also clean, and the current GitHub Actions/Conformance/Zizmor checks are green.

@StantonMatt StantonMatt left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I retested the latest head (721dd43) against the shutdown case I called out earlier.

The new bounded drain path covers both sides of that tradeoff for me: test_server_drains_in_flight_handlers_on_transport_read_eof still lets already-started handlers flush responses after stdin EOF, and test_server_bounds_drain_on_read_eof_when_handler_never_finishes covers the hung-handler case so EOF stays bounded.

Local focused check passed:

TMPDIR=.codex-tmp/tmp UV_CACHE_DIR=.codex-tmp/uv-cache uv run --frozen pytest tests/server/test_cancel_handling.py tests/server/test_stdio.py -q

GitHub checks are green on the current head as well. No further concern from my earlier note.

Copy link
Copy Markdown

Would POSIX pipe backpressure/disconnect tests belong in this PR, or should they remain a #3674 follow-up? This scenario goes beyond the stated assumption that the client continues reading stdout.

At head 7d386fb72ebbb1e3b457fe50959119dd08ee5d00, two narrow diagnostics observed no exit within a five-second watchdog when stdout remained unread after stdin EOF, and exit 1 with BrokenPipeError when stdout was closed instead. These are observations, not confirmation of a PR bug: the environment used AnyIO 4.14.2 rather than the locked 4.10.0, and neither the full PR nor its locked environment was validated.

Could you clarify the intended disconnect semantics and whether transport-write shutdown shares the handler-drain bound? A separate POSIX candidate uses a one-second writer drain, but that policy has not been agreed with maintainers. The shared Windows hangs remain unresolved.

I am not assigned to #3674 and have not submitted these tests. AI assistance was used for the review, diagnostics, and this question.

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

7 issues found across 9 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="tests/server/test_cancel_handling.py">

<violation number="1" location="tests/server/test_cancel_handling.py:171">
P2: Closing the input immediately after releasing the handler lets read EOF cancel it before it is guaranteed to attempt its response, so this test may pass without exercising a send on the closed write stream. Keep the input open until the handler's response attempt has completed.</violation>
</file>

<file name="src/mcp/server/lowlevel/server.py">

<violation number="1" location="src/mcp/server/lowlevel/server.py:703">
P2: This reintroduces `Server.run(stateless=)` as a no-op, despite the migration guide saying the flag was removed and statelessness comes from connection construction. Remove this parameter and its misleading documentation.</violation>

<violation number="2" location="src/mcp/server/lowlevel/server.py:714">
P1: The default deadline cancels any in-flight handler still running one second after stdin EOF, so slower tools can still lose the response this change is meant to preserve. Give stdio callers a configurable, suitable drain deadline or avoid timing out handler execution.</violation>
</file>

<file name="src/mcp/shared/jsonrpc_dispatcher.py">

<violation number="1" location="src/mcp/shared/jsonrpc_dispatcher.py:512">
P2: With the default `True` setting, EOF closes the write stream before the task group cancels its handlers, so `_handle_request` cannot send its `CONNECTION_CLOSED` shutdown response. Keep the writer open until the task-group join completes, then close it.</violation>

<violation number="2" location="src/mcp/shared/jsonrpc_dispatcher.py:525">
P2: Set `_closed` when EOF starts draining: a handler that calls `ctx.session.create_message()` during this window sees `_running=False` but `_closed=False` and raises the misleading “before run” `RuntimeError` instead of `CONNECTION_CLOSED`.</violation>
</file>

<file name="src/mcp/server/stdio.py">

<violation number="1" location="src/mcp/server/stdio.py:258">
P2: Explicit `anyio.wrap_file(sys.stdout)` is recognized here, but it skips `_claim_fd`, so its timed-out writer is not recorded in `_claims`. A later default transport can then write to the same pipe concurrently and corrupt frames; guard explicit process stdout with the pending-writer claim too.</violation>

<violation number="2" location="src/mcp/server/stdio.py:279">
P2: `os.dup(output_fileno)` can raise `OSError` (for example, `EMFILE`) and abort `stdio_server()` instead of using the existing stream-write fallback. Catch the error and leave `stdout_fd` as `None`.</violation>
</file>

Reply with feedback, questions, or to request a fix.

Re-trigger cubic

drain_on_read_close: bool = False,
# Maximum time to wait for in-flight handlers to drain after read EOF.
# None means wait indefinitely.
read_eof_drain_timeout_seconds: float | None = DEFAULT_READ_EOF_DRAIN_TIMEOUT_SECONDS,

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1: The default deadline cancels any in-flight handler still running one second after stdin EOF, so slower tools can still lose the response this change is meant to preserve. Give stdio callers a configurable, suitable drain deadline or avoid timing out handler execution.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At src/mcp/server/lowlevel/server.py, line 714:

<comment>The default deadline cancels any in-flight handler still running one second after stdin EOF, so slower tools can still lose the response this change is meant to preserve. Give stdio callers a configurable, suitable drain deadline or avoid timing out handler execution.</comment>

<file context>
@@ -698,6 +700,18 @@ async def run(
+        drain_on_read_close: bool = False,
+        # Maximum time to wait for in-flight handlers to drain after read EOF.
+        # None means wait indefinitely.
+        read_eof_drain_timeout_seconds: float | None = DEFAULT_READ_EOF_DRAIN_TIMEOUT_SECONDS,
     ) -> None:
         """Serve a single connection over the given streams until the read side closes.
</file context>

# Close the server's input stream — this is what stdin EOF does.
# server.run()'s incoming_messages loop ends, finally-cancel fires,
# handler gets CancelledError, server.run() returns.
await to_server.aclose()

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Closing the input immediately after releasing the handler lets read EOF cancel it before it is guaranteed to attempt its response, so this test may pass without exercising a send on the closed write stream. Keep the input open until the handler's response attempt has completed.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At tests/server/test_cancel_handling.py, line 171:

<comment>Closing the input immediately after releasing the handler lets read EOF cancel it before it is guaranteed to attempt its response, so this test may pass without exercising a send on the closed write stream. Keep the input open until the handler's response attempt has completed.</comment>

<file context>
@@ -107,17 +108,79 @@ async def first_request():
+            # Close the server's input stream — this is what stdin EOF does.
+            # server.run()'s incoming_messages loop ends, finally-cancel fires,
+            # handler gets CancelledError, server.run() returns.
+            await to_server.aclose()
+
+            handler_allowed_to_finish.set()
</file context>

# but also make tracing exceptions much easier during testing and when using
# in-process servers.
raise_exceptions: bool = False,
# When True, the server is stateless and

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: This reintroduces Server.run(stateless=) as a no-op, despite the migration guide saying the flag was removed and statelessness comes from connection construction. Remove this parameter and its misleading documentation.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At src/mcp/server/lowlevel/server.py, line 703:

<comment>This reintroduces `Server.run(stateless=)` as a no-op, despite the migration guide saying the flag was removed and statelessness comes from connection construction. Remove this parameter and its misleading documentation.</comment>

<file context>
@@ -698,6 +700,18 @@ async def run(
         # but also make tracing exceptions much easier during testing and when using
         # in-process servers.
         raise_exceptions: bool = False,
+        # When True, the server is stateless and
+        # clients can perform initialization with any node. The client must still follow
+        # the initialization lifecycle, but can do so with any available node
</file context>

# Receive end closed under us (stateless SHTTP teardown); same as EOF.
logger.debug("read stream closed by transport; treating as EOF")
# EOF: wake blocked `send_raw_request` waiters with CONNECTION_CLOSED.
self._running = False

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Set _closed when EOF starts draining: a handler that calls ctx.session.create_message() during this window sees _running=False but _closed=False and raises the misleading “before run” RuntimeError instead of CONNECTION_CLOSED.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At src/mcp/shared/jsonrpc_dispatcher.py, line 525:

<comment>Set `_closed` when EOF starts draining: a handler that calls `ctx.session.create_message()` during this window sees `_running=False` but `_closed=False` and raises the misleading “before run” `RuntimeError` instead of `CONNECTION_CLOSED`.</comment>

<file context>
@@ -487,40 +499,50 @@ async def run(
+                            # Receive end closed under us (stateless SHTTP teardown); same as EOF.
+                            logger.debug("read stream closed by transport; treating as EOF")
+                    # EOF: wake blocked `send_raw_request` waiters with CONNECTION_CLOSED.
+                    self._running = False
+                    self._fan_out_closed()
+                    normal_eof = True
</file context>
Suggested change
self._running = False
self._running = False
self._closed = True

async with AsyncExitStack() as stack:
await stack.enter_async_context(self._read_stream)
if self._close_write_stream_on_read_close:
await stack.enter_async_context(self._write_stream)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: With the default True setting, EOF closes the write stream before the task group cancels its handlers, so _handle_request cannot send its CONNECTION_CLOSED shutdown response. Keep the writer open until the task-group join completes, then close it.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At src/mcp/shared/jsonrpc_dispatcher.py, line 512:

<comment>With the default `True` setting, EOF closes the write stream before the task group cancels its handlers, so `_handle_request` cannot send its `CONNECTION_CLOSED` shutdown response. Keep the writer open until the task-group join completes, then close it.</comment>

<file context>
@@ -487,40 +499,50 @@ async def run(
+                    async with AsyncExitStack() as stack:
+                        await stack.enter_async_context(self._read_stream)
+                        if self._close_write_stream_on_read_close:
+                            await stack.enter_async_context(self._write_stream)
+                        try:
+                            async for item in self._read_stream:
</file context>

Comment thread src/mcp/server/stdio.py
else:
# Windows CRT writes lock their fd. Keep restoration's source
# descriptor separate so dup2 cannot wait on a blocked write.
stdout_fd = os.dup(output_fileno)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: os.dup(output_fileno) can raise OSError (for example, EMFILE) and abort stdio_server() instead of using the existing stream-write fallback. Catch the error and leave stdout_fd as None.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At src/mcp/server/stdio.py, line 279:

<comment>`os.dup(output_fileno)` can raise `OSError` (for example, `EMFILE`) and abort `stdio_server()` instead of using the existing stream-write fallback. Catch the error and leave `stdout_fd` as `None`.</comment>

<file context>
@@ -170,16 +252,51 @@ async def stdio_server(stdin: anyio.AsyncFile[str] | None = None, stdout: anyio.
+            else:
+                # Windows CRT writes lock their fd. Keep restoration's source
+                # descriptor separate so dup2 cannot wait on a blocked write.
+                stdout_fd = os.dup(output_fileno)
+
+        def write_stdout(text: str) -> None:
</file context>
Suggested change
stdout_fd = os.dup(output_fileno)
try:
stdout_fd = os.dup(output_fileno)
except OSError:
pass

Comment thread src/mcp/server/stdio.py
writer_stopped = threading.Event()
writer: _StdoutWriter | None = None
stdout_fd: int | None = None
process_stdout = stdout is None or stdout.wrapped is sys.stdout

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Explicit anyio.wrap_file(sys.stdout) is recognized here, but it skips _claim_fd, so its timed-out writer is not recorded in _claims. A later default transport can then write to the same pipe concurrently and corrupt frames; guard explicit process stdout with the pending-writer claim too.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At src/mcp/server/stdio.py, line 258:

<comment>Explicit `anyio.wrap_file(sys.stdout)` is recognized here, but it skips `_claim_fd`, so its timed-out writer is not recorded in `_claims`. A later default transport can then write to the same pipe concurrently and corrupt frames; guard explicit process stdout with the pending-writer claim too.</comment>

<file context>
@@ -170,16 +252,51 @@ async def stdio_server(stdin: anyio.AsyncFile[str] | None = None, stdout: anyio.
+    writer_stopped = threading.Event()
+    writer: _StdoutWriter | None = None
+    stdout_fd: int | None = None
+    process_stdout = stdout is None or stdout.wrapped is sys.stdout
+    output_encoding = "utf-8"
+    output_errors = "strict"
</file context>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

FastMCP/stdio: in-flight tool responses dropped on stdin EOF when input is bash-redirected from a file

3 participants