Refuse abnormal processes instead of repairing them in stdio isolation

The stdin/stdout claim now engages only in a normal process: the sys
stream backed by its real descriptor and fds 0-2 all open, which makes
it impossible for the private wire duplicates to land in the standard
range. Anything else - replaced streams, an incomplete descriptor
table, a failed dup - is served in place exactly as v1 was, and a
second concurrent stdio_server() raises RuntimeError instead of
contending for the streams.

This replaces the previous hardening (the dup-above-standard-range
loop, stderr-merge detection, and nested transports serving into the
diversion) with guards, and removes the migration entry: no working
code changes behavior, so there is nothing to migrate. Comments and
docstrings trimmed throughout the diff.

Author: maxisbey

docs/migration.md

@@ -1855,41 +1855,6 @@ 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 streams on private descriptors
-
-While serving on the process's real stdin and stdout, the stdio server transport now
-duplicates each protocol pipe to a private descriptor and points the standard
-descriptors — with their Windows standard handles — away from the wire, restoring
-both when the transport exits: fd 0 reads the null device, and fd 1 writes to stderr
-(the null device if stderr is unusable). Subprocesses started by handler code
-therefore inherit the diversions instead of the protocol pipes, and a stray
-`print()` lands on stderr rather than the wire. (The claim is best-effort: in the
-rare process whose descriptor table cannot be rearranged, the transport serves in
-place, exactly as v1 did.)
-
-In v1 a child inheriting the pipes could consume protocol bytes or corrupt the
-outgoing stream with its own output, 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 (and capturing the child's
-stdout) 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 used the standard streams directly during a
-stdio session. Reading `sys.stdin` (or calling `input()`) now sees end-of-file
-instead of racing the transport for protocol bytes; there was never a meaningful
-value to read there. `print()` and other `sys.stdout` writes reach stderr instead of
-corrupting the wire — code that deliberately wrote protocol frames to `sys.stdout`
-must send them through the transport's write stream instead. A child that streams
-a lot of output to its inherited stdout now streams it into the client's stderr
-channel; capture output you don't want in the client's logs. Likewise, anything
-that read ahead from `sys.stdin` before the server started keeps those bytes; they
-no longer reach the transport (they never reliably did). Passing an explicit `stdin=`/`stdout=` stream to
-`stdio_server(...)` skips the descriptor changes for that stream, as does any
-environment where the sys stream is not backed by the process's real descriptor.
-
 ### 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/troubleshooting.md

@@ -137,7 +137,7 @@ There is no error string for this, which is exactly why it is hard to search. Th
 * **Is the tool on the `mcp` the host is running?** A second `MCPServer(...)` in another module is a different, empty server. Check which object the host's command actually imports.
 * **Did two tools share a name?** Then one of them is gone. Look for `Tool already exists:` in the server log.
 * **Is the host's list stale?** Adding a tool after startup only reaches clients that handle `notifications/tools/list_changed`. Restarting the host is the blunt fix.
-* **Did something write to `stdout` before the server started serving?** While serving, the SDK diverts stray stdout to stderr (best-effort: an environment that replaces `sys.stdout`, or merges stderr into stdout on Windows, is served as-is), but output flushed to stdout earlier -- a wrapper script echoing, an import-time `print()` in an unbuffered process -- lands on the protocol stream, and one junk line can make the host drop the connection, which some hosts render as a server with nothing in it. Log with the `logging` module instead. The rest of the host-side checklist is on **[Connect to a real host](get-started/real-host.md)**.
+* **Did something write to `stdout` before the server started serving?** While serving, the SDK diverts stray stdout to stderr (best-effort: an environment that replaces the standard streams is served as-is), but output flushed to stdout earlier -- a wrapper script echoing, an import-time `print()` in an unbuffered process -- lands on the protocol stream, and one junk line can make the host drop the connection, which some hosts render as a server with nothing in it. Log with the `logging` module instead. The rest of the host-side checklist is on **[Connect to a real host](get-started/real-host.md)**.
 
 An "invalid" tool name is *not* on that list: a non-conforming name logs a warning but the tool is registered and listed anyway.
 

src/mcp/os/posix/utilities.py

@@ -1,31 +1,15 @@
-"""POSIX-specific functionality for stdio transport operations."""
+"""POSIX-specific functionality for stdio client operations."""
 
 import logging
 import os
 import signal
-import sys
 from contextlib import suppress
 
 import anyio
 from anyio.abc import Process
 
 logger = logging.getLogger(__name__)
 
-
-def same_open_file(fd_a: int, fd_b: int) -> bool:
-    """Whether two descriptors refer to the same open file.
-
-    False on Windows - anonymous pipe handles carry no identity to compare -
-    and False when either descriptor cannot be interrogated.
-    """
-    if sys.platform == "win32":
-        return False
-    try:
-        return os.path.sameopenfile(fd_a, fd_b)
-    except OSError:
-        return False
-
-
 # How often to probe for surviving group members between SIGTERM and SIGKILL.
 _GROUP_POLL_INTERVAL = 0.01
 

src/mcp/os/win32/utilities.py

@@ -34,14 +34,11 @@
 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.
+    os.dup2 updates only the CRT descriptor table; subprocess handle inheritance
+    reads the Win32 slot, so it must be repointed too.
 
     Raises:
-        OSError: The slot could not be set; callers treat descriptor
-            rearrangement as best-effort and fall back on failure.
+        OSError: The slot could not be set.
     """
     if sys.platform != "win32" or not win32api or not win32file or not pywintypes:
         return

src/mcp/server/stdio.py

@@ -1,15 +1,9 @@
-"""Stdio Server Transport Module
-
-This module provides functionality for creating an stdio-based transport layer
-that can be used to communicate with an MCP client through standard input/output
-streams.
+"""Stdio server transport for MCP.
 
 Example:
     ```python
     async def run_server():
         async with stdio_server() as (read_stream, write_stream):
-            # read_stream contains incoming JSONRPCMessages from stdin
-            # write_stream allows sending JSONRPCMessages to stdout
             server = await create_my_server()
             await server.run(read_stream, write_stream, init_options)
 
@@ -29,109 +23,59 @@ async def run_server():
 import anyio.lowlevel
 import mcp_types as types
 
-from mcp.os.posix.utilities import same_open_file
 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
 
-# Descriptors a transport in this process currently has pointed away from
-# their protocol pipes. A second concurrent stdio_server() must not claim an
-# fd again: it would duplicate the diversion target instead of the protocol
-# pipe, and its restore would clobber the first transport's. The lock makes
-# the check-and-claim atomic for embedders running transports on threads.
 _claimed: set[int] = set()
 _claimed_lock = threading.Lock()
 
 
 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 _dup_above_std(fd: int) -> int:
-    """Duplicates fd onto a descriptor above the standard range (fd > 2).
-
-    os.dup hands out the lowest free slot, so in a process started with a
-    standard descriptor closed the private wire duplicate would itself become
-    fd 0, 1, or 2 - handed to children as a standard stream, and, when it
-    lands on fd 2, silently made the target of the stdout diversion.
-
-    Raises:
-        OSError: propagated from os.dup; nothing is leaked into the standard
-            range - every duplicate made so far is closed first.
-    """
-    duplicates = [os.dup(fd)]
+def _std_descriptors_open() -> bool:
+    """Whether fds 0-2 are all open, so a dup cannot land in the standard range."""
     try:
-        while duplicates[-1] <= 2:
-            duplicates.append(os.dup(fd))
+        for fd in (0, 1, 2):
+            os.fstat(fd)
     except OSError:
-        for duplicate in duplicates:
-            os.close(duplicate)
-        raise
-    for below_std in duplicates[:-1]:
-        os.close(below_std)
-    return duplicates[-1]
+        return False
+    return True
 
 
 def _open_stdin_diversion() -> int:
-    """What fd 0 reads while claimed: the null device, so readers see EOF."""
     return os.open(os.devnull, os.O_RDONLY)
 
 
 def _open_stdout_diversion() -> int:
-    """What fd 1 receives while claimed: stderr, where stray output is at least
-    visible in the client's logs, or the null device when stderr is unusable
-    or is itself the wire (stderr merged into stdout, the 2>&1 launch shape -
-    detectable on POSIX; on Windows such a merge keeps its v1 behavior)."""
-    if not same_open_file(2, 1):
-        try:
-            return os.dup(2)
-        except OSError:
-            pass
-    return os.open(os.devnull, os.O_WRONLY)
+    try:
+        return os.dup(2)
+    except OSError:
+        return os.open(os.devnull, os.O_WRONLY)
 
 
 def _claim_fd(
     fd: int, stream: TextIO, mode: Literal["rb", "wb"], open_diversion: Callable[[], int]
 ) -> tuple[BinaryIO, Callable[[], None] | None]:
-    """Returns the binary stream the transport uses for the protocol, and its undo.
-
-    When stream is the process's real standard stream, moves the protocol pipe
-    to a private descriptor and points fd (and, on Windows, the matching
-    standard handle) at the diversion for the transport's lifetime, so handler
-    code and its child processes touch the diversion instead of the protocol
-    pipe; stdio_server's docstring describes the resulting behavior.
-
-    The claim is best-effort: when the descriptors cannot be rearranged the
-    transport serves the sys stream's buffer in place, exactly as before
-    isolation existed, and when a transport in this process already claimed
-    fd it serves a fresh buffered view of wherever fd currently points. In
-    both cases the undo callback is None. A stream with no real descriptor
-    is served through its own buffer.
+    """Move the protocol pipe to a private descriptor and divert fd while serving.
+
+    Raises:
+        RuntimeError: fd is already claimed by another transport in this process.
     """
-    if not _is_backed_by_fd(stream, fd):
+    if not _is_backed_by_fd(stream, fd) or not _std_descriptors_open():
         return stream.buffer, None
-    # Claimed before touching the descriptor table so a second transport
-    # entering mid-claim serves in place instead of duplicating a half-moved
-    # descriptor.
     with _claimed_lock:
-        already_claimed = fd in _claimed
-        if not already_claimed:
-            _claimed.add(fd)
-    if already_claimed:
-        # An enclosing transport owns the claim. Serve wherever fd currently
-        # points - the diversion - through a fresh view rather than the sys
-        # stream's buffer: its cached seekability describes the pre-claim
-        # target, and interrogating it can fail on the retargeted descriptor.
-        return open(fd, mode, closefd=False), None
+        if fd in _claimed:
+            raise RuntimeError(f"another stdio_server() in this process has already claimed fd {fd}")
+        _claimed.add(fd)
     private_fd = None
     try:
-        private_fd = _dup_above_std(fd)
+        private_fd = os.dup(fd)
         diversion_fd = open_diversion()
         try:
             os.dup2(diversion_fd, fd)
@@ -140,43 +84,27 @@ def _claim_fd(
         if sys.platform == "win32":  # pragma: no cover
             rebind_std_handle_to_fd(fd)
     except OSError:
-        with _claimed_lock:
-            _claimed.discard(fd)
+        # Undo before unclaiming: fd stays claimed for as long as it is diverted.
         if private_fd is not None:
-            # A completed dup2 is undone; an untouched fd is re-pointed at
-            # the same pipe it already holds, which is harmless.
             _restore_fd(fd, private_fd)
             os.close(private_fd)
-        # fd still holds the protocol pipe, so the sys stream's buffer is
-        # target-consistent: serve it in place, exactly as v1 did - shared
-        # write ordering, no new descriptors to allocate in a process whose
-        # descriptor table is already failing.
+        with _claimed_lock:
+            _claimed.discard(fd)
         return stream.buffer, None
 
     def restore() -> None:
-        # Flush first: text buffered in the sys stream during the claim (a
-        # stray print() while stdout is claimed) drains to the diversion, not
-        # to the restored protocol pipe.
+        # Drain text buffered during the claim (a stray print) to the diversion.
         with suppress(OSError, ValueError):
             stream.flush()
         _restore_fd(fd, private_fd)
         with _claimed_lock:
             _claimed.discard(fd)
 
-    # closefd=False: an I/O call may sit blocked 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. The
-    # private descriptor is deliberately left open for the same reason - one
-    # descriptor per stream per session, restore() only points fd back at it.
+    # closefd=False: a blocked worker thread may still read this descriptor after exit.
     return os.fdopen(private_fd, mode, 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
@@ -185,23 +113,13 @@ def _restore_fd(fd: int, private_fd: int) -> None:
 
 @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 and stdout, the transport claims
-    them: each protocol pipe moves to a private descriptor, fd 0 (with the
-    Windows standard input handle) reads the null device, and fd 1 (with the
-    standard output handle) is diverted to stderr — the null device if stderr
-    is unusable. Handler code and the child processes it spawns can therefore
-    neither consume protocol bytes nor corrupt the outgoing stream: reads see
-    end-of-file, and stray writes (a `print()`, a child's inherited stdout)
-    land on stderr. Both descriptors are restored when the context exits.
-    Passing an explicit stream skips the claim for that side.
+    """Serve MCP over the process's stdin and stdout.
+
+    While serving, fd 0 points at the null device and fd 1 at stderr — handlers
+    and children read EOF and stray output misses the wire — both restored on exit.
+    Explicit streams skip the claim; a second concurrent stdio_server() raises RuntimeError.
     """
-    # 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.
+    # Re-wrap the binary buffers as UTF-8 text; the std handles' platform encodings are unreliable.
     restore_stdin: Callable[[], None] | None = None
     restore_stdout: Callable[[], None] | None = None
     try:

tests/interaction/_requirements.py

@@ -3919,9 +3919,9 @@ def __post_init__(self) -> None:
                 "While serving, stdio_server moves the wire to private descriptors and diverts fd 0/1, so "
                 "handler code and its child processes can neither read protocol bytes nor write into the "
                 "stream (pinned by tests/server/test_stdio.py). Remaining gaps: output flushed to stdout "
-                "before the transport enters can still precede the first frame; the claim is best-effort "
-                "and skipped for explicitly injected streams; and a stderr merged into stdout (2>&1) is "
-                "detected and neutralized only on POSIX - Windows pipe handles carry no identity."
+                "before the transport enters can still precede the first frame, and the claim is "
+                "best-effort - skipped for explicitly injected streams and for processes without "
+                "normal standard descriptors."
             ),
         ),
     ),