claude-code - 💡(How to fix) Fix [DOCS] MCP stdio server docs missing stdout/stderr protocol guidance [1 participants]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/mcp

Section/Topic

Option 3: Add a local stdio server in the MCP docs, plus the stdio servers and troubleshooting guidance in the Agent SDK MCP docs.

Current Documentation

The MCP docs currently say:

Option 3: Add a local stdio server

Stdio servers run as local processes on your machine. They're ideal for tools that need direct system access or custom scripts.

The Agent SDK MCP docs currently say:

stdio servers

Local processes that communicate via stdin/stdout. Use this for MCP servers you run on the same machine:

The Agent SDK troubleshooting section lists missing environment variables, missing installs, invalid connection strings, network issues, and slow initialization, but it does not explain that stdio server stdout must stay reserved for MCP protocol traffic or that diagnostic output should go to stderr.

What's Wrong or Missing?

Claude Code v2.1.110 fixed this changelog item:

Fixed stdio MCP servers that print stray non-JSON lines to stdout being disconnected on the first stray line (regression in 2.1.105)

That fix exposes an important setup/troubleshooting detail that the docs still do not explain: for stdio MCP servers, stdout is the protocol channel. If a custom server, wrapper script, shell startup, or dependency prints banners/logging/non-JSON text to stdout, the connection can fail or behave unpredictably.

The current docs tell users how to add local stdio servers, but they do not tell them:

1. stdout should be reserved for MCP JSON-RPC traffic
2. logs/debug output should go to stderr instead of stdout
3. stray stdout output is a concrete thing to check when a stdio server fails to connect or disconnects unexpectedly

Suggested Improvement

Add a short note in the local stdio server sections explaining the transport expectation explicitly, for example:

Important: For stdio MCP servers, stdout is reserved for MCP protocol messages. Do not print banners, logs, or other non-JSON text to stdout. Send diagnostics to stderr instead.

Also add a troubleshooting bullet such as:

If a local stdio server fails to connect, disconnects unexpectedly, or shows Connection closed, check whether the server or any wrapper script is writing stray output to stdout during startup or while running.

This should appear in both the general MCP docs and the Agent SDK MCP troubleshooting section so users configuring custom/local servers get the same guidance in both places.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 2 pages affected

Source: Changelog v2.1.110

Exact changelog entry: Fixed stdio MCP servers that print stray non-JSON lines to stdout being disconnected on the first stray line (regression in 2.1.105)