Re-point fd at the wire when a divert dup2 fails

A Windows dup2 (UCRT before Windows 11) closes its target before
duplicating, so an OSError from the divert can leave the standard
descriptor closed rather than still carrying the wire. Run the same
dup2(private_fd, fd) restore the exit path uses before serving in
place: an idempotent no-op when fd is already on the wire, and a
re-materialization from the private duplicate when the target was
closed. Adds a regression variant that closes the target as UCRT does.

Also scopes the real-host logging note to the default stderr handler.

Author: maxisbey

docs/get-started/real-host.md

@@ -165,7 +165,7 @@ Once that command sits and waits, what's left is almost always one of three thin
 
 * **A relative path.** The host launches your server from *its* working directory, not the one you registered from. `server.py` where `/absolute/path/to/server.py` is needed is the single most common failure. If the host can't find `uv` either, that path has to be absolute too.
 * **The host is still running its old config.** Hosts read their config at launch. Claude Desktop in particular has to be *fully quit* (not just its window closed) and reopened before an edit to `claude_desktop_config.json` takes effect.
-* **Something reached stdout outside the diverted window.** On stdio, stdout *is* the protocol. The SDK diverts flushed stray output to stderr while serving, but output flushed to stdout before then (a wrapper script echoing, an import-time `print()` in an unbuffered process), or a buffered `print()` drained at interpreter exit, hands the host a corrupt message and it drops the connection. Log with the `logging` module, which flushes each record to stderr. **[Logging](../handlers/logging.md)** has the whole story.
+* **Something reached stdout outside the diverted window.** On stdio, stdout *is* the protocol. The SDK diverts flushed stray output to stderr while serving, but output flushed to stdout before then (a wrapper script echoing, an import-time `print()` in an unbuffered process), or a buffered `print()` drained at interpreter exit, hands the host a corrupt message and it drops the connection. Log with the default `logging` configuration, whose stderr handler flushes each record; custom handlers must also avoid stdout. **[Logging](../handlers/logging.md)** has the whole story.
 
 Claude Desktop keeps a log per server: `mcp-server-<NAME>.log` is your server's stderr, next to `mcp.log` for connections, under `~/Library/Logs/Claude` on macOS and `%APPDATA%\Claude\logs` on Windows.
 

src/mcp/server/stdio.py

@@ -140,10 +140,12 @@ def release() -> None:
     try:
         os.dup2(diversion_fd, fd)
     except OSError:
-        # The divert did not land; fd still carries the wire, so serve it in
-        # place through the shared buffer (two writers on one pipe tear frames).
+        # The divert did not land; ensure fd carries the wire (a Windows dup2 can
+        # close its target before failing), then serve it in place through the
+        # shared buffer, since two writers on one pipe would tear frames.
         with suppress(OSError):
             os.close(diversion_fd)
+        _restore_fd(fd, private_fd)
         return stream.buffer, release
     with suppress(OSError):
         os.close(diversion_fd)

tests/server/test_stdio.py

@@ -214,14 +214,15 @@ async def test_stdio_server_takes_stdin_off_the_descriptor_table_while_serving(
 
 
 @pytest.mark.anyio
-@pytest.mark.parametrize("failing_call", ["dup", "dup2"])
+@pytest.mark.parametrize("failing_call", ["dup", "dup2", "dup2_destroys_target"])
 async def test_stdio_server_reads_stdin_in_place_when_descriptor_isolation_fails(
     failing_call: str, monkeypatch: pytest.MonkeyPatch
 ) -> None:
     """A descriptor failure while claiming stdin degrades to reading sys.stdin in place.
 
     SDK-defined behavior: isolation is best-effort; when duplicating fd 0 or diverting
-    it fails, the transport serves over the original stdin exactly as v1 did.
+    it fails, the transport serves over the original stdin exactly as v1 did. A dup2
+    that closes its target before failing (Windows UCRT) still leaves fd 0 on the wire.
     """
     request = JSONRPCRequest(jsonrpc="2.0", id=1, method="ping")
     with _pipe_planted_on_fd0(monkeypatch) as (in_r, in_w):
@@ -237,13 +238,16 @@ def failing_dup_above_std(fd: int) -> int:
             monkeypatch.setattr("mcp.server.stdio._dup_above_std", failing_dup_above_std)
         else:
             # Fires once at the divert, then passes through: pytest's capture
-            # machinery also calls os.dup2 at phase transitions.
+            # machinery also calls os.dup2 at phase transitions. The destroying
+            # variant closes the target first, as Windows UCRT dup2 does.
             real_dup2 = os.dup2
             armed = [True]
 
             def failing_dup2(fd: int, fd2: int, inheritable: bool = True) -> int:
                 if armed[0]:
                     armed[0] = False
+                    if failing_call == "dup2_destroys_target":
+                        os.close(fd2)
                     raise OSError("injected descriptor failure")
                 return real_dup2(fd, fd2, inheritable)