claude-code - 💡(How to fix) Fix [DOCS] [MCP] Stdout parsing edge case not documented — servers emitting non-protocol data cause unbounded memory growth [1 participants]

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

"Option 3: Add a local stdio server" section (lines 286–310), specifically the description of stdio transport behavior

Current Documentation

The MCP documentation describes how to configure stdio servers:

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

The documentation includes configuration syntax and notes about option ordering, but does not explain:

• What stdout is expected to contain for a stdio MCP server
• That the v2.1.132 release fixed severe memory growth (10GB+ RSS) caused by non-protocol stdout from a stdio server
• How to identify or debug when a server is emitting stray stdout

What's Wrong or Missing?

The v2.1.132 changelog documents this failure mode directly:

Fixed unbounded memory growth (10GB+ RSS) when a stdio MCP server writes non-protocol data to stdout

The MCP and troubleshooting docs do not explain the stdout contract for stdio servers, what "non-protocol data" means in practice, or how users should diagnose this symptom. Server authors also are not told to send logging and debug output to stderr instead of stdout.

Suggested Improvement

Add a "Stdio server behavior and troubleshooting" subsection to the MCP docs covering:

1. Expectation: Stdio servers should emit only MCP protocol messages to stdout. Logging, progress output, and debug text should go to stderr.

2. Memory impact: The v2.1.132 changelog documents that non-protocol stdout from a stdio server was able to trigger unbounded memory growth in long sessions.

3. Debugging tip: If you see unexplained memory growth while using stdio MCP servers, inspect the server for stray stdout output and rerun with debug logging.

4. Changelog cross-reference: Note that v2.1.132 fixed a case where this scenario caused 10GB+ RSS memory growth.

Add to troubleshooting.md:

• A note in the "High CPU or memory usage" section linking MCP servers as a potential cause when stdio servers emit non-protocol data.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Changelog reference: v2.1.132 entry: "Fixed unbounded memory growth (10GB+ RSS) when a stdio MCP server writes non-protocol data to stdout"

Root cause scope: This is a behavior edge case that was fixed internally. Documentation would help users recognize when their own MCP servers hit this scenario.