Isolate the stdio server's stdin from handler subprocesses

While serving on the process's real stdin, stdio_server() now reads the
protocol from a private duplicate of fd 0 and points fd 0 (and, on
Windows, the standard input handle) at the null device, restoring both
on exit. Children spawned by handler code then inherit the null device
instead of the protocol pipe.

A child that inherited the pipe could consume protocol bytes on any
platform, and on Windows a Python child hangs inside interpreter
startup behind the transport's pending read (CPython gh-78961) until
the next request arrives, so any tool that ran a subprocess without
stdin=DEVNULL appeared to hang until timeout.

Isolation engages only when sys.stdin is backed by the real fd 0, at
most once per process, and degrades to reading stdin in place when the
descriptor table cannot be rearranged.

Fixes #671.

Author: maxisbey

docs/migration.md

@@ -1855,6 +1855,29 @@ group (spawned with `start_new_session=True`); the `getpgid()` lookup and the
 per-process terminate/kill fallback are gone. The win32 utilities logger is now
 named `mcp.os.win32.utilities` (was `client.stdio.win32`).
 
+### `stdio_server` keeps the protocol stdin on a private descriptor
+
+While serving on the process's real stdin, the stdio server transport now duplicates
+the protocol pipe to a private descriptor and points fd 0 — and, on Windows, the
+standard input handle — at the null device, restoring both when the transport exits.
+Subprocesses started by handler code therefore inherit the null device instead of the
+protocol pipe. (The claim is best-effort: in the rare process whose descriptor table
+cannot be rearranged, the transport serves stdin in place, exactly as v1 did.)
+
+Previously a child inheriting the pipe could consume protocol bytes, and on Windows
+hung at interpreter startup until the next request arrived — the
+[#671](https://github.com/modelcontextprotocol/python-sdk/issues/671) hang; the
+mechanism and the `stdin=subprocess.DEVNULL` workaround for older versions live in
+the [troubleshooting entry](troubleshooting.md#my-stdio-tool-hangs-when-it-starts-a-subprocess-on-windows).
+
+To migrate: nothing, unless handler code read `sys.stdin` (or called `input()`)
+during a stdio session — it now sees end-of-file instead of racing the transport for
+protocol bytes; there was never a meaningful value to read there. Likewise, bytes
+something buffered out of `sys.stdin` before the server started no longer reach the
+transport (they never reliably did). Passing explicit `stdin=`/`stdout=` streams to
+`stdio_server(...)` skips the descriptor changes entirely, as does any environment
+where `sys.stdin` is not backed by the process's real fd 0.
+
 ### WebSocket transport removed
 
 The WebSocket transport has been removed: `mcp.client.websocket.websocket_client`, `mcp.server.websocket.websocket_server`, and the `ws` optional dependency extra (`mcp[ws]`) no longer exist. WebSocket was never part of the MCP specification. Use the streamable HTTP transport instead (`mcp.client.streamable_http.streamable_http_client` on the client, `streamable_http_app()` on the server), which supports bidirectional communication with server-to-client streaming over standard HTTP.

docs/run/index.md

@@ -41,29 +41,7 @@ Nothing prints, and it doesn't return. It is waiting on stdin for a host to spea
 
 That also means stdout **is the wire**. A stray `print()` corrupts the stream; the `logging` module writes to stderr and is the right tool. That story is in **[Logging](../handlers/logging.md)**.
 
-On Windows, the same rule applies to child processes your tools start. A child
-that inherits the stdio server's stdin can block behind the server's protocol
-reader. If your tool starts a subprocess and you do not intend to feed it input,
-redirect the child's stdin:
-
-```python
-import asyncio
-import subprocess
-import sys
-
-
-async def run_script() -> tuple[bytes, bytes]:
-    process = await asyncio.create_subprocess_exec(
-        sys.executable,
-        "script.py",
-        stdin=subprocess.DEVNULL,
-        stdout=subprocess.PIPE,
-        stderr=subprocess.PIPE,
-    )
-    return await process.communicate()
-```
-
-The matching troubleshooting entry is **[My stdio tool hangs when it starts a subprocess on Windows](../troubleshooting.md#my-stdio-tool-hangs-when-it-starts-a-subprocess-on-windows)**.
+stdin, on the other hand, is guarded for you. While the server runs, the protocol's stdin lives on a private descriptor and fd 0 is the null device, so a subprocess your tool starts gets the null device instead of the protocol pipe — on older SDK versions that inheritance hung Python children on Windows. The child does still inherit stdout — the wire — unless you capture it, so pipe the child's output like the example in **[My stdio tool hangs when it starts a subprocess on Windows](../troubleshooting.md#my-stdio-tool-hangs-when-it-starts-a-subprocess-on-windows)**, which also has the mechanism and the redirection to use on older versions.
 
 ### Try it
 

docs/troubleshooting.md

@@ -143,38 +143,17 @@ An "invalid" tool name is *not* on that list: a non-conforming name logs a warni
 
 ## My stdio tool hangs when it starts a subprocess on Windows
 
-Your server is running over `stdio`, and a tool starts another process with
-`asyncio.create_subprocess_exec`, `asyncio.create_subprocess_shell`, or
-`subprocess.Popen`. The tool call never returns on Windows, while the same code
-works over an HTTP transport.
+Your server is running over `stdio`, and a tool starts another process — `subprocess.run`, `subprocess.Popen`, `asyncio.create_subprocess_exec`. On Windows the call never returns, while the same code works over an HTTP transport. And if the client sends *another* request, the stuck call completes at that exact moment: hangs-until-the-timeout-then-suddenly-ran is the signature of this one.
 
-The child inherited the server's stdin. In a stdio server, stdin is the protocol
-pipe and the server is already waiting on it for the next JSON-RPC message. A
-Python child process on Windows can block during startup when it inherits that
-same pipe.
+The child inherited the server's stdin: the protocol pipe, which the transport always has a blocking read pending on. Windows serializes operations on a pipe like that, and a Python child touches its inherited stdin during interpreter startup ([CPython gh-78961](https://github.com/python/cpython/issues/78961)) — so the child freezes *before your script's first line* until the pending read completes, which is exactly when the next JSON-RPC message arrives. Skipping the redirections entirely doesn't dodge it, either: Windows hands a console child the parent's standard handles even then.
 
-If you do not intend to send input to the child, redirect its stdin:
+Current versions of the SDK defuse the collision: while it serves, `stdio_server` moves the protocol pipe to a private descriptor and leaves the null device on fd 0 (and on the Windows standard input handle), so a child has nothing of the transport's to inherit. If you can reproduce this hang, you are on an older version — or wiring `stdio_server(stdin=..., stdout=...)` to explicit streams yourself, which skips the guard (as does the rare process whose descriptor table can't be rearranged; the transport then serves stdin in place, as older versions did). Upgrade, or redirect the child's stdin:
 
-```python
-import asyncio
-import subprocess
-import sys
-
-
-async def run_script() -> tuple[bytes, bytes]:
-    process = await asyncio.create_subprocess_exec(
-        sys.executable,
-        "script.py",
-        stdin=subprocess.DEVNULL,
-        stdout=subprocess.PIPE,
-        stderr=subprocess.PIPE,
-    )
-    return await process.communicate()
+```python title="server.py" hl_lines="16"
+--8<-- "docs_src/troubleshooting/tutorial009.py"
 ```
 
-Use the same idea with `subprocess.Popen(..., stdin=subprocess.DEVNULL)`. Also
-capture or redirect the child's stdout. The stdio server's stdout is the MCP
-wire, so a child that writes there can corrupt the connection.
+`stdin=subprocess.DEVNULL` is the line that matters, and the same argument works for `subprocess.run`, `subprocess.Popen`, and `asyncio.create_subprocess_shell`. It stays good hygiene on any version and any platform: a child you don't mean to feed input has no business holding your stdin. Capturing the child's stdout, as above, is its stdout-side twin — see the warning about the wire in **[Running your server](run/index.md#stdio)**.
 
 ## `MCPError: Server returned an error response`
 

docs_src/troubleshooting/tutorial009.py

@@ -0,0 +1,23 @@
+import asyncio
+import subprocess
+import sys
+
+from mcp.server import MCPServer
+
+mcp = MCPServer("Runner")
+
+
+@mcp.tool()
+async def run_script(path: str) -> str:
+    """Run a Python script and return what it printed."""
+    process = await asyncio.create_subprocess_exec(
+        sys.executable,
+        path,
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+    stdout, stderr = await process.communicate()
+    if process.returncode != 0:
+        raise ValueError(f"script failed: {stderr.decode().strip()}")
+    return stdout.decode().strip()

src/mcp/os/win32/utilities.py

@@ -1,4 +1,4 @@
-"""Windows-specific functionality for stdio client operations."""
+"""Windows-specific functionality for stdio transport operations."""
 
 import logging
 import shutil
@@ -20,14 +20,39 @@
     import pywintypes
     import win32api
     import win32con
+    import win32file
     import win32job
 else:
     # Type stubs for non-Windows platforms
     win32api = None
     win32con = None
+    win32file = None
     win32job = None
     pywintypes = None
 
+
+def rebind_std_handle_to_fd(fd: int) -> None:
+    """Points the Win32 standard-handle slot for fd 0, 1, or 2 at fd's current OS handle.
+
+    os.dup2 updates only the C runtime's descriptor table; anything that resolves
+    GetStdHandle — subprocess standard-handle inheritance, native code — reads the
+    Win32 slot, so after retargeting a standard descriptor the slot must be
+    repointed too.
+
+    Raises:
+        OSError: The slot could not be set; callers treat descriptor
+            rearrangement as best-effort and fall back on failure.
+    """
+    if sys.platform != "win32" or not win32api or not win32file or not pywintypes:
+        return
+    std_ids = {0: win32api.STD_INPUT_HANDLE, 1: win32api.STD_OUTPUT_HANDLE, 2: win32api.STD_ERROR_HANDLE}
+    try:
+        win32api.SetStdHandle(std_ids[fd], win32file._get_osfhandle(fd))
+    except pywintypes.error as exc:
+        # Normalized so callers' OSError-based best-effort handling covers it.
+        raise OSError(f"SetStdHandle failed for fd {fd}") from exc
+
+
 # How often FallbackProcess polls the underlying Popen for exit.
 _EXIT_POLL_INTERVAL = 0.01
 

src/mcp/server/stdio.py

@@ -17,61 +17,159 @@ async def run_server():
     ```
 """
 
+import os
 import sys
-from contextlib import asynccontextmanager
+from collections.abc import Callable
+from contextlib import asynccontextmanager, suppress
 from io import TextIOWrapper
+from typing import BinaryIO, TextIO
 
 import anyio
 import anyio.lowlevel
 import mcp_types as types
 
+from mcp.os.win32.utilities import rebind_std_handle_to_fd
 from mcp.shared._context_streams import create_context_streams
 from mcp.shared.message import SessionMessage
 
+# True while a transport in this process has fd 0 pointed at the null device.
+# A second concurrent stdio_server() must not claim again: it would duplicate
+# the null device instead of the protocol pipe, and its restore would clobber
+# the first transport's.
+_stdin_claimed = False
+
+
+def _is_backed_by_fd(stream: TextIO, fd: int) -> bool:
+    """Whether stream is a text wrapper over the process's real descriptor fd."""
+    try:
+        return stream.buffer.fileno() == fd
+    except (AttributeError, OSError, ValueError):
+        # In-memory or injected streams (tests, embedders) have no usable
+        # descriptor; io.UnsupportedOperation is a subclass of OSError/ValueError.
+        return False
+
+
+def _claim_stdin() -> tuple[BinaryIO, Callable[[], None] | None]:
+    """Returns the binary stream the transport reads the protocol from, and its undo.
+
+    When running on the process's real stdin, moves the protocol pipe to a
+    private descriptor and points fd 0 (and, on Windows, the standard input
+    handle) at the null device for the transport's lifetime. Child processes
+    spawned by handlers then inherit the null device instead of the protocol
+    pipe: a child holding the protocol pipe could consume protocol bytes, and
+    on Windows a Python child hangs during interpreter startup while the
+    transport's blocking read is pending on the shared pipe
+    (https://github.com/python/cpython/issues/78961).
+
+    Isolation is best-effort: when the descriptors cannot be rearranged, or a
+    transport in this process already claimed stdin, the returned stream is
+    sys.stdin.buffer read in place (the pre-isolation behavior) and the undo
+    callback is None.
+    """
+    global _stdin_claimed
+    if _stdin_claimed or not _is_backed_by_fd(sys.stdin, 0):
+        return sys.stdin.buffer, None
+    # Set before touching the descriptor table so a second transport entering
+    # mid-claim serves in place instead of duplicating a half-moved fd 0.
+    _stdin_claimed = True
+    private_fd = None
+    try:
+        private_fd = os.dup(0)
+        devnull_fd = os.open(os.devnull, os.O_RDONLY)
+        try:
+            os.dup2(devnull_fd, 0)
+        finally:
+            os.close(devnull_fd)
+        if sys.platform == "win32":  # pragma: no cover
+            rebind_std_handle_to_fd(0)
+    except OSError:
+        _stdin_claimed = False
+        # Isolation is best-effort: serve stdin in place, as before it existed.
+        if private_fd is not None:
+            # A completed dup2 is undone; an untouched fd 0 is re-pointed at
+            # the same pipe it already holds, which is harmless.
+            _restore_fd(0, private_fd)
+            os.close(private_fd)
+        return sys.stdin.buffer, None
+
+    def restore() -> None:
+        global _stdin_claimed
+        _restore_fd(0, private_fd)
+        _stdin_claimed = False
+
+    # closefd=False: the reader may sit in a blocking read on this descriptor
+    # in a worker thread past the transport's lifetime, so garbage collection
+    # of the wrapper must never close (and free for reuse) the fd under it.
+    return os.fdopen(private_fd, "rb", closefd=False), restore
+
+
+def _restore_fd(fd: int, private_fd: int) -> None:
+    """Points fd back at the protocol stream the transport claimed.
+
+    Best-effort: a failure must never mask whatever ended the transport, so it
+    is swallowed rather than raised out of stdio_server's finally.
+    """
+    with suppress(OSError):
+        os.dup2(private_fd, fd)
+        if sys.platform == "win32":  # pragma: no cover
+            rebind_std_handle_to_fd(fd)
+
 
 @asynccontextmanager
 async def stdio_server(stdin: anyio.AsyncFile[str] | None = None, stdout: anyio.AsyncFile[str] | None = None):
     """Server transport for stdio: this communicates with an MCP client by reading
     from the current process' stdin and writing to stdout.
+
+    While serving on the process's real stdin, the transport claims it: the
+    protocol pipe moves to a private descriptor and fd 0 (with the Windows
+    standard input handle) reads the null device, so handler code and its
+    child processes cannot touch the protocol stream. Both are restored when
+    the context exits. Passing an explicit stdin skips this entirely.
     """
     # Purposely not using context managers for these, as we don't want to close
     # standard process handles. Encoding of stdin/stdout as text streams on
     # python is platform-dependent (Windows is particularly problematic), so we
     # re-wrap the underlying binary stream to ensure UTF-8.
-    if not stdin:
-        stdin = anyio.wrap_file(TextIOWrapper(sys.stdin.buffer, encoding="utf-8", errors="replace"))
-    if not stdout:
-        stdout = anyio.wrap_file(TextIOWrapper(sys.stdout.buffer, encoding="utf-8"))
+    restore_stdin: Callable[[], None] | None = None
+    try:
+        if not stdin:
+            stdin_buffer, restore_stdin = _claim_stdin()
+            stdin = anyio.wrap_file(TextIOWrapper(stdin_buffer, encoding="utf-8", errors="replace"))
+        if not stdout:
+            stdout = anyio.wrap_file(TextIOWrapper(sys.stdout.buffer, encoding="utf-8"))
 
-    read_stream_writer, read_stream = create_context_streams[SessionMessage | Exception](0)
-    write_stream, write_stream_reader = create_context_streams[SessionMessage](0)
+        read_stream_writer, read_stream = create_context_streams[SessionMessage | Exception](0)
+        write_stream, write_stream_reader = create_context_streams[SessionMessage](0)
 
-    async def stdin_reader():
-        try:
-            async with read_stream_writer:
-                async for line in stdin:
-                    try:
-                        message = types.jsonrpc_message_adapter.validate_json(line, by_name=False)
-                    except Exception as exc:
-                        await read_stream_writer.send(exc)
-                        continue
-
-                    session_message = SessionMessage(message)
-                    await read_stream_writer.send(session_message)
-        except anyio.ClosedResourceError:  # pragma: no cover
-            await anyio.lowlevel.checkpoint()
-
-    async def stdout_writer():
-        try:
-            async with write_stream_reader:
-                async for session_message in write_stream_reader:
-                    json = session_message.message.model_dump_json(by_alias=True, exclude_unset=True)
-                    await stdout.write(json + "\n")
-                    await stdout.flush()
-        except anyio.ClosedResourceError:  # pragma: no cover
-            await anyio.lowlevel.checkpoint()
-
-    async with anyio.create_task_group() as tg:
-        tg.start_soon(stdin_reader)
-        tg.start_soon(stdout_writer)
-        yield read_stream, write_stream
+        async def stdin_reader():
+            try:
+                async with read_stream_writer:
+                    async for line in stdin:
+                        try:
+                            message = types.jsonrpc_message_adapter.validate_json(line, by_name=False)
+                        except Exception as exc:
+                            await read_stream_writer.send(exc)
+                            continue
+
+                        session_message = SessionMessage(message)
+                        await read_stream_writer.send(session_message)
+            except anyio.ClosedResourceError:  # pragma: no cover
+                await anyio.lowlevel.checkpoint()
+
+        async def stdout_writer():
+            try:
+                async with write_stream_reader:
+                    async for session_message in write_stream_reader:
+                        json = session_message.message.model_dump_json(by_alias=True, exclude_unset=True)
+                        await stdout.write(json + "\n")
+                        await stdout.flush()
+            except anyio.ClosedResourceError:  # pragma: no cover
+                await anyio.lowlevel.checkpoint()
+
+        async with anyio.create_task_group() as tg:
+            tg.start_soon(stdin_reader)
+            tg.start_soon(stdout_writer)
+            yield read_stream, write_stream
+    finally:
+        if restore_stdin is not None:
+            restore_stdin()