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

@@ -1863,6 +1863,32 @@ 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.)
+
+In v1 a child inheriting the pipe could consume protocol bytes, and on Windows it
+hung inside interpreter startup — behind the transport's pending read on the shared
+pipe ([CPython gh-78961](https://github.com/python/cpython/issues/78961)) — until
+the next request arrived: the
+[#671](https://github.com/modelcontextprotocol/python-sdk/issues/671) hang, for
+which passing `stdin=subprocess.DEVNULL` on every spawn was the required
+workaround. On v2 the workaround is no longer needed, for any spawn API,
+redirected or not.
+
+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,30 +41,6 @@ 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)**.
-
 ### Try it
 
 ```console

docs/troubleshooting.md

@@ -141,41 +141,6 @@ There is no error string for this, which is exactly why it is hard to search. Th
 
 An "invalid" tool name is *not* on that list: a non-conforming name logs a warning but the tool is registered and listed anyway.
 
-## 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.
-
-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.
-
-If you do not intend to send input to the child, redirect its 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()
-```
-
-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.
-
 ## `MCPError: Server returned an error response`
 
 The server refused the HTTP request outright, with a body that is not JSON-RPC, so the python `Client` has nothing better to show you than this stand-in.

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()