[DOCS] MCP stdio server docs missing malformed stdout troubleshooting

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 and stdio MCP troubleshooting/error handling

Current Documentation

The current docs explain how to configure stdio MCP servers, but they do not explain the stdout/stderr contract or the malformed-output failure mode.

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

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

And later on the same page:

Without the cmd /c wrapper, you'll encounter "Connection closed" errors because Windows cannot directly execute npx.

From https://code.claude.com/docs/en/agent-sdk/mcp:

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

The Agent SDK troubleshooting section currently lists only these common causes for failed connections:

Missing environment variables: Ensure required tokens and credentials are set. For stdio servers, check the env field matches what the server expects. Server not installed: For npx commands, verify the package exists and Node.js is in your PATH. Invalid connection string: For database servers, verify the connection string format and that the database is accessible. Network issues: For remote HTTP/SSE servers, check the URL is reachable and any firewalls allow the connection.

What's Wrong or Missing?

The docs never state that stdio MCP servers must keep stdout reserved for MCP protocol traffic and send diagnostic logs to stderr. That omission matters because changelog v2.1.105 fixed a case where a stdio MCP server emitting malformed (non-JSON) output could hang the session instead of failing fast with Connection closed.

Right now, the only explicit Connection closed guidance on the main MCP page is the Windows cmd /c npx wrapper note. Users and MCP server authors do not get any documentation that:

• non-JSON or other malformed output on stdout can break a stdio MCP connection
• stdout should be protocol-only for stdio transports
• logs and debug output should go to stderr instead
• Connection closed can also indicate malformed stdio output, not just the Windows npx wrapper problem

That leaves a real troubleshooting gap for anyone building or debugging local stdio MCP servers.

Suggested Improvement

Add a short warning/note under Option 3: Add a local stdio server in https://code.claude.com/docs/en/mcp and a matching note in https://code.claude.com/docs/en/agent-sdk/mcp.

Suggested content outline:

1. State the transport contract explicitly: for stdio MCP servers, stdout is reserved for MCP protocol messages.
2. Tell server authors to write logs, debug messages, and banners to stderr, not stdout.
3. Add a troubleshooting bullet that malformed or non-JSON stdout can cause the server to disconnect with Connection closed.
4. Clarify that Connection closed is a generic stdio transport symptom and not only the Windows cmd /c / npx case.

Example wording:

Warning: For stdio MCP servers, reserve stdout for MCP protocol messages only. If the server prints logs or other non-JSON output to stdout, Claude Code may fail the connection with Connection closed. Send logs and debug output to stderr instead.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/mcp | Main MCP setup page; documents stdio server configuration and currently mentions Connection closed only for the Windows cmd /c wrapper case |
| https://code.claude.com/docs/en/agent-sdk/mcp | Agent SDK MCP page; documents stdio transport and troubleshooting but does not mention malformed stdout / non-JSON output |

Total scope: 2 pages affected

Source: Changelog v2.1.105

Changelog entry:

Fixed stdio MCP server emitting malformed (non-JSON) output hanging the session instead of failing fast with "Connection closed"