Skip to content
13 changes: 13 additions & 0 deletions docs/run/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,19 @@ Nothing prints, and it doesn't return. It is waiting on stdin for a host to spea

That also means stdout **is the wire**. While serving, the SDK moves the wire to a private descriptor and diverts output that is *flushed* to stdout (a subprocess writing to its inherited stdout, a flushed `print()`) to stderr, where it can't corrupt the stream. Output flushed to stdout *before* serving begins (a wrapper script echoing, an unbuffered import-time print) still lands on the wire, and so does a `print()` that stays buffered until the interpreter drains it at exit. For output you actually want, the `logging` module is the right tool: its handler flushes each record to stderr as it happens. That story is in **[Logging](../handlers/logging.md)**.

When stdin reaches EOF, the server gives in-flight handlers a drain window (one second by default)
to finish their responses. After the session returns, the stdio transport gives pending output
up to one additional second to finish writing. These are separate budgets: the handler timeout
does not bound the entire process shutdown, including application cleanup.

Keep reading stdout after closing stdin if you need the remaining responses. If stdout stays
full and unread, transport shutdown stops waiting when its output drain expires; an unfinished
response may be lost. A closed stdout read end still surfaces a write error such as
`BrokenPipeError`. The SDK does not close caller-supplied streams. If a timed-out write is still
running, another stdio transport on the same process output is refused until that write finishes.
For custom output streams, the caller must also let any abandoned write finish before closing
or reusing the stream.

### Try it

```console
Expand Down
17 changes: 17 additions & 0 deletions src/mcp/server/lowlevel/server.py
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,8 @@ async def main():

logger = logging.getLogger(__name__)

DEFAULT_READ_EOF_DRAIN_TIMEOUT_SECONDS = 1.0

LifespanResultT = TypeVar("LifespanResultT", default=Any)

_ParamsT = TypeVar("_ParamsT", bound=BaseModel, default=BaseModel)
Expand Down Expand Up @@ -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

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>

# clients can perform initialization with any node. The client must still follow
# the initialization lifecycle, but can do so with any available node
# rather than requiring initialization for each connection.
stateless: bool = False,
# When True, treat read EOF as a half-close and allow in-flight handlers
# to drain their responses via the still-open write stream (e.g. stdio
# with bash-redirected stdin).
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>

) -> None:
"""Serve a single connection over the given streams until the read side closes.

Expand All @@ -715,6 +729,9 @@ async def run(
lifespan_state=lifespan_context,
init_options=initialization_options,
raise_exceptions=raise_exceptions,
session_id=None,
close_write_stream_on_read_close=not drain_on_read_close,
read_eof_drain_timeout_seconds=read_eof_drain_timeout_seconds,
)

def streamable_http_app(
Expand Down
1 change: 1 addition & 0 deletions src/mcp/server/mcpserver/server.py
Original file line number Diff line number Diff line change
Expand Up @@ -1022,6 +1022,7 @@ async def run_stdio_async(self) -> None:
read_stream,
write_stream,
self._lowlevel_server.create_initialization_options(),
drain_on_read_close=True,
)

async def run_sse_async( # pragma: no cover
Expand Down
28 changes: 26 additions & 2 deletions src/mcp/server/runner.py
Original file line number Diff line number Diff line change
Expand Up @@ -476,6 +476,8 @@ async def serve_loop(
session_id: str | None = None,
init_options: InitializationOptions | None = None,
raise_exceptions: bool = False,
close_write_stream_on_read_close: bool = True,
read_eof_drain_timeout_seconds: float | None = None,
) -> None:
"""Drive ``server`` in handshake-only loop mode over a stream pair until the channel closes.

Expand All @@ -494,6 +496,8 @@ async def serve_loop(
# next request (spec: SHOULD NOT, not MUST NOT) sees the initialized
# state instead of failing the init-gate.
inline_methods=frozenset({"initialize"}),
close_write_stream_on_read_close=close_write_stream_on_read_close,
read_eof_drain_timeout_seconds=read_eof_drain_timeout_seconds,
)
connection = Connection.for_loop(dispatcher, session_id=session_id)
await serve_connection(
Expand Down Expand Up @@ -608,6 +612,8 @@ async def serve_dual_era_loop(
session_id: str | None = None,
init_options: InitializationOptions | None = None,
raise_exceptions: bool = False,
close_write_stream_on_read_close: bool = True,
read_eof_drain_timeout_seconds: float | None = None,
) -> None:
"""Drive `server` over a duplex stream pair, in the era the client opens with.

Expand All @@ -630,7 +636,13 @@ async def serve_dual_era_loop(
)
if opens_modern:
await _serve_modern_stream(
server, replayed, write_stream, lifespan_state=lifespan_state, raise_exceptions=raise_exceptions
server,
replayed,
write_stream,
lifespan_state=lifespan_state,
raise_exceptions=raise_exceptions,
close_write_stream_on_read_close=close_write_stream_on_read_close,
read_eof_drain_timeout_seconds=read_eof_drain_timeout_seconds,
)
else:
await _serve_legacy_stream(
Expand All @@ -641,6 +653,8 @@ async def serve_dual_era_loop(
session_id=session_id,
init_options=init_options,
raise_exceptions=raise_exceptions,
close_write_stream_on_read_close=close_write_stream_on_read_close,
read_eof_drain_timeout_seconds=read_eof_drain_timeout_seconds,
)
finally:
await write_stream.aclose()
Expand Down Expand Up @@ -723,6 +737,8 @@ async def _serve_legacy_stream(
session_id: str | None,
init_options: InitializationOptions | None,
raise_exceptions: bool,
close_write_stream_on_read_close: bool,
read_eof_drain_timeout_seconds: float | None,
) -> None:
"""Serve a 2025 handshake connection; enveloped requests are refused."""
dispatcher: JSONRPCDispatcher[TransportContext] = JSONRPCDispatcher(
Expand All @@ -731,6 +747,8 @@ async def _serve_legacy_stream(
raise_handler_exceptions=raise_exceptions,
# `initialize` inline for the same pipelining reason as `serve_loop`.
inline_methods=frozenset({"initialize"}),
close_write_stream_on_read_close=close_write_stream_on_read_close,
read_eof_drain_timeout_seconds=read_eof_drain_timeout_seconds,
)
connection = Connection.for_loop(dispatcher, session_id=session_id)
runner = ServerRunner(server, connection, lifespan_state, init_options=init_options)
Expand Down Expand Up @@ -759,10 +777,16 @@ async def _serve_modern_stream(
*,
lifespan_state: LifespanT,
raise_exceptions: bool,
close_write_stream_on_read_close: bool,
read_eof_drain_timeout_seconds: float | None,
) -> None:
"""Serve a 2026-07-28 connection: every request carries its own envelope."""
dispatcher: JSONRPCDispatcher[TransportContext] = JSONRPCDispatcher(
read_stream, write_stream, raise_handler_exceptions=raise_exceptions
read_stream,
write_stream,
raise_handler_exceptions=raise_exceptions,
close_write_stream_on_read_close=close_write_stream_on_read_close,
read_eof_drain_timeout_seconds=read_eof_drain_timeout_seconds,
)
outbound = NotifyOnlyOutbound(dispatcher)

Expand Down
162 changes: 151 additions & 11 deletions src/mcp/server/stdio.py
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,11 @@ async def run_server():
"""

import os
import queue
import sys
import threading
from collections.abc import Callable
from concurrent.futures import CancelledError
from contextlib import asynccontextmanager, suppress
from dataclasses import dataclass
from io import TextIOWrapper
Expand All @@ -23,6 +25,7 @@ async def run_server():
import anyio
import anyio.lowlevel
import mcp_types as types
from anyio.from_thread import BlockingPortal

from mcp.os.win32.utilities import rebind_std_handle_to_fd
from mcp.shared._context_streams import create_context_streams
Expand All @@ -41,12 +44,15 @@ async def run_server():
# diverted descriptor. Every failure lands on that safe side.
_claims: dict[int, "_StreamClaim"] = {}
_claims_lock = threading.Lock()
_STDOUT_DRAIN_TIMEOUT_SECONDS = 1.0


@dataclass
class _StreamClaim:
fd: int
private_fd: int | None = None
pending_io: threading.Event | None = None
released: bool = False


class _UnownedTextWrapper(TextIOWrapper):
Expand Down Expand Up @@ -104,7 +110,11 @@ def _restore_fd(fd: int, private_fd: int) -> bool:


def _claim_fd(
fd: int, stream: TextIO, mode: Literal["rb", "wb"], open_diversion: Callable[[], int]
fd: int,
stream: TextIO,
mode: Literal["rb", "wb"],
open_diversion: Callable[[], int],
pending_io: threading.Event | None = None,
) -> tuple[BinaryIO, Callable[[], None] | None]:
"""Claim a standard stream: divert fd and serve the wire from a private duplicate.

Expand All @@ -116,16 +126,28 @@ def _claim_fd(
"""
if not _is_backed_by_fd(stream, fd):
return stream.buffer, None
claim = _StreamClaim(fd)
claim = _StreamClaim(fd, pending_io=pending_io)
with _claims_lock:
previous = _claims.get(fd)
if (
previous is not None
and previous.released
and previous.pending_io is not None
and previous.pending_io.is_set()
):
del _claims[fd]
if fd in _claims:
raise RuntimeError(f"another stdio_server() in this process has already claimed fd {fd}")
_claims[fd] = claim

def release() -> None:
if claim.private_fd is None or _restore_fd(fd, claim.private_fd):
with _claims_lock:
del _claims[fd]
claim.released = True
# A timed-out writer still owns the wire. Refuse a successor
# until it finishes, even though fd 1 has been restored.
if claim.pending_io is None or claim.pending_io.is_set():
del _claims[fd]

try:
private_fd = _dup_above_std(fd)
Expand Down Expand Up @@ -158,6 +180,66 @@ def release() -> None:
return os.fdopen(private_fd, mode, closefd=False), release


class _StdoutWriter:
"""One daemon thread, with at most one response awaiting completion."""

def __init__(
self,
write: Callable[[str], None],
close: Callable[[], None],
portal: BlockingPortal,
stopped: threading.Event,
) -> None:
self._write = write
self._close = close
self._portal = portal
self._stopped = stopped
self._finished = anyio.Event()
self._stopping = threading.Event()
self._queue: queue.SimpleQueue[tuple[str, anyio.Event] | None] = queue.SimpleQueue()
self._error: Exception | None = None
self._thread = threading.Thread(target=self._run, name="mcp-stdout", daemon=True)

def start(self) -> None:
self._thread.start()

def _run(self) -> None:
try:
while (item := self._queue.get()) is not None:
text, complete = item
try:
self._write(text)
except Exception as exc:
# Thread boundary: report the original write/flush failure
# from the async writer, rather than losing it in the thread.
self._error = exc
if not self._stopping.is_set():
# A write can complete after the drain deadline and portal exit.
with suppress(RuntimeError, CancelledError):
self._portal.call(complete.set)
if self._error is not None:
return
finally:
self._close()
self._stopped.set()
with suppress(RuntimeError, CancelledError):
self._portal.call(self._finished.set)

async def write(self, text: str) -> None:
complete = anyio.Event()
self._queue.put((text, complete))
await complete.wait()
if self._error is not None:
raise self._error

def stop(self) -> None:
self._stopping.set()
self._queue.put(None)

async def wait_stopped(self) -> None:
await self._finished.wait()


@asynccontextmanager
async def stdio_server(stdin: anyio.AsyncFile[str] | None = None, stdout: anyio.AsyncFile[str] | None = None):
"""Serve MCP over the process's stdin and stdout.
Expand All @@ -170,16 +252,51 @@ async def stdio_server(stdin: anyio.AsyncFile[str] | None = None, stdout: anyio.
# 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
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>

output_encoding = "utf-8"
output_errors = "strict"
if stdout is not None and stdout.wrapped is sys.stdout:
output_encoding = sys.stdout.encoding or "utf-8"
output_errors = sys.stdout.errors or "strict"
try:
if not stdin:
stdin_buffer, restore_stdin = _claim_fd(0, sys.stdin, "rb", _open_stdin_diversion)
stdin = anyio.wrap_file(_UnownedTextWrapper(stdin_buffer, encoding="utf-8", errors="replace"))
if not stdout:
stdout_buffer, restore_stdout = _claim_fd(1, sys.stdout, "wb", _open_stdout_diversion)
stdout_buffer, restore_stdout = _claim_fd(1, sys.stdout, "wb", _open_stdout_diversion, writer_stopped)
stdout = anyio.wrap_file(_UnownedTextWrapper(stdout_buffer, encoding="utf-8"))
if process_stdout:
try:
output_fileno = stdout.wrapped.fileno()
except (AttributeError, OSError, ValueError):
pass
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


def write_stdout(text: str) -> None:
if stdout_fd is None:
stdout.wrapped.write(text)
stdout.wrapped.flush()
else:
# Bypass buffered locks, including sys.stdout.buffer in the
# degraded path: Python flushes that buffer during finalization.
data = memoryview(text.replace("\n", os.linesep).encode(output_encoding, errors=output_errors))
while data:
written = os.write(stdout_fd, data)
data = data[written:]

def close_stdout() -> None:
if stdout_fd is not None:
os.close(stdout_fd)

read_stream_writer, read_stream = create_context_streams[SessionMessage | Exception](0)
write_stream, write_stream_reader = create_context_streams[SessionMessage](0)
stdout_done = anyio.Event()

async def stdin_reader():
try:
Expand All @@ -201,16 +318,39 @@ async def stdout_writer():
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
assert writer is not None
await writer.write(json + "\n")
except anyio.ClosedResourceError:
await anyio.lowlevel.checkpoint()
finally:
stdout_done.set()

async with anyio.create_task_group() as tg:
tg.start_soon(stdin_reader)
tg.start_soon(stdout_writer)
yield read_stream, write_stream
async with BlockingPortal() as portal:
writer = _StdoutWriter(write_stdout, close_stdout, portal, writer_stopped)
writer.start()
drain_deadline = float("inf")
try:
async with anyio.create_task_group() as tg:
tg.start_soon(stdin_reader)
tg.start_soon(stdout_writer)
try:
yield read_stream, write_stream
finally:
await write_stream.aclose()
# This is a separate transport budget, after the caller's
# handler drain. Cancelling an AnyIO file worker cannot
# interrupt write(2) or let its non-daemon thread exit.
drain_deadline = anyio.current_time() + _STDOUT_DRAIN_TIMEOUT_SECONDS
with anyio.CancelScope(deadline=drain_deadline, shield=True):
await stdout_done.wait()
tg.cancel_scope.cancel()
finally:
writer.stop()
with anyio.CancelScope(deadline=drain_deadline, shield=True):
await writer.wait_stopped()
finally:
if writer is None:
writer_stopped.set()
if restore_stdout is not None:
restore_stdout()
if restore_stdin is not None:
Expand Down
Loading
Loading