Repository navigation
stdio_server: text a tool prints still reaches the client, because sys.stdout is flushed after fd 1 is restored #3821
Description
Summary
Since #3117, stdio_server() points fd 1 at stderr while it serves, so that stray output from handlers misses the wire. Text written with print() still reaches the client. It goes into sys.stdout's own buffer, which is block-buffered when stdout is a pipe. That buffer is flushed when the interpreter exits, after stdio_server() has given fd 1 back to the client's pipe. The client then reads the text as a JSON-RPC message.
Reproduction
mcp 2.3.0, Python 3.13.16, macOS 26.3.
import asyncio
import sys
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
from mcp.server.mcpserver import MCPServer
if sys.argv[1:] == ["server"]:
server = MCPServer("repro")
@server.tool()
def noisy() -> str:
print("stray output from a tool") # e.g. a library that prints
return "done"
server.run("stdio")
else:
async def main():
params = StdioServerParameters(command=sys.executable, args=[__file__, "server"])
async with stdio_client(params) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
result = await session.call_tool("noisy", {})
print("result:", result.content[0].text)
asyncio.run(main())Running python repro.py, the call succeeds, and the client also logs:
pydantic_core._pydantic_core.ValidationError: 1 validation error for union[JSONRPCRequest,JSONRPCNotification,JSONRPCResponse,JSONRPCError]
Invalid JSON: expected value at line 1 column 1 [type=json_invalid, input_value='stray output from a tool', input_type=str]
Cause
While fd 1 is diverted, the printed text never reaches it: it sits in sys.stdout's buffer. The buffer is written out at interpreter exit, when fd 1 is the protocol pipe again. Adding sys.stdout.flush() right after the print() in the tool removes the error, and the text appears on stderr, which confirms this.
Suggestion
Flush sys.stdout before restoring fd 1, so that pending text goes to the diversion. Making sys.stdout line-buffered while serving (sys.stdout.reconfigure(line_buffering=True)) would also send printed text to stderr when it is printed, rather than at exit.
As a workaround we call sys.stdout.reconfigure(line_buffering=True) before server.run("stdio") and flush after each tool.
Activity
ima-d-ice commentedon Nov 5, 2026
I looked through the implementation in
src/mcp/server/stdio.pyand I think I understand the root cause.The
_claim_fd()release callback restores fd 1 without first flushing the originalsys.stdoutwrapper. Buffered output can therefore be written to the protocol pipe after the descriptor has been restored.I think a targeted fix would be to flush the captured stdout stream before restoring fd 1, while ensuring descriptor restoration still happens even if flushing fails.
I'd also like to add a regression test in
tests/server/test_stdio.pythat usesprint()withoutflush=Trueand verifies that the buffered output reaches stderr rather than the JSON-RPC stream.Does this approach align with the intended behavior? I'd be interested in contributing the implementation and tests.
AI assistance disclosure: I used ChatGPT to help with initial code-path analysis and drafting. I'll verify the behavior and take responsibility for the implementation.
media-ctrl commentedon Nov 5, 2026
Confirmed at the fd level on current main, and the distinction matters for where the fix goes.
_claim_fd()insrc/mcp/server/stdio.pydoesos.dup2(diversion_fd, 1)to point fd 1 at a dup of fd 2, and returnsrelease(). That closure calls_restore_fd(fd, claim.private_fd), which isos.dup2(private_fd, 1). Nothing in the release path touchessys.stdout, so every byte sitting in the interpreter's own wrapper is still pending at the moment fd 1 becomes the wire again.stdio_server()'sfinallyonly callsrestore_stdout(). Theawait stdout.flush()at line 205 cannot help: that flushes the private_UnownedTextWrapperthe transport serves, notsys.stdout.I reproduced the mechanism with a control on a fresh fixture instead of a real server, so the three cases are separable:
Measured, Python 3.13, stdout a pipe:
'stray output from a tool\n'''sys.stdout.flush()before restore'''stray output from a tool\n'reconfigure(line_buffering=True)at claim'''stray output from a tool\n'One more measurement that explains why this reads as intermittent. The wrapper is block-buffered at 8192 bytes, so output at or above that size flushes into the diversion mid-serve and never reaches the wire. Writing
"S" * n:So a one-line warning from a library always corrupts the stream, and a large debug blob usually does not. The small prints are the ones people believe are harmless, and they are the guaranteed failures.
For the fix,
_claim_fd()already receivesstream: TextIO, which issys.stdout, so the object is in scope inside therelease()closure. Flushingstreamthere, before_restore_fd(), covers both the diverted and the no-diversion path (claim.private_fd is None) with one code path. It also cannot interleave with a protocol frame, because the writer serializes to the private descriptor rather than tosys.stdout.Your line-buffering suggestion is the better of the two for latency, but it changes buffering for the rest of the process unless the previous state is saved and put back on release. Flush-on-release is the smaller change if the maintainers want one line.