mcp-stdio-guard: A CLI for catching MCP stdio bugs before clients fail

[1Utkarsh1]

Pre-submission Checklist

• This post follows the MCP community guidelines

What would you like to share?

What I built

I built mcp-stdio-guard, a small CLI tool that helps MCP developers test stdio servers before they break inside real MCP clients.

MCP stdio servers use stdout as the protocol channel, which means stdout must stay clean and only contain valid JSON-RPC messages. In real projects, it is very easy to accidentally break this with a console.log, startup banner, debug print, Python print(), progress message, or invalid JSON-RPC frame.

mcp-stdio-guard runs an MCP server command behind a guard, performs a real MCP initialize handshake, sends notifications/initialized, and can optionally send a real post-initialize request such as tools/list. It then checks whether stdout stayed valid and reports clear errors if something corrupted the MCP stream.

How I built it

I built it as a zero-runtime-dependency Node.js CLI.

Basic usage:

npx mcp-stdio-guard -- node ./server.js

I also made a small example gist showing the guard in action with passing and failing MCP stdio behaviour:

https://gist.github.com/1Utkarsh1/90d7a0f2ea85635e3a209eb1be4970f9

To test a real MCP request after initialization:

npx mcp-stdio-guard --request tools/list -- node ./server.js

To use it in CI with static scanning:

npx mcp-stdio-guard --scan src --fail-on-static --request tools/list -- node ./server.js

It also supports JSON output for CI tools, registries, and badges:

npx mcp-stdio-guard --json --request tools/list -- node ./server.js

And repeat mode to catch cold/warm startup issues:

npx mcp-stdio-guard --repeat 2 --request tools/list -- node ./server.js

What problems it catches

The tool can catch:

• accidental stdout pollution before startup
• console.log or console.info in JavaScript/TypeScript MCP servers
• Python print() writing to stdout instead of stderr
• invalid JSON-RPC frames
• Content-Length style framing accidentally written to stdout
• missing initialize responses
• missing responses to post-initialize requests like tools/list
• server crashes after initialization
• late stdout logs after the MCP connection starts
• Python buffering issues in stdio servers
• risky stdout writes found through optional static scanning

Challenges I faced

The biggest challenge was making the guard test the real process boundary, not just the server code. MCP stdio failures often happen outside the main logic of the server. For example, a dependency can print during import time, a developer can leave a debug log in startup code, or Python buffering can cause confusing behaviour.

Another challenge was keeping the output useful for both humans and automation. I wanted local debugging output to be readable, but I also wanted JSON output that CI systems and registries could consume reliably.

What I learned

I learned that MCP stdio correctness is not only about implementing the right tools or using the right SDK. The process boundary matters a lot. Since stdout is the protocol channel, any non-protocol output can break the client.

I also learned that a small developer tool can be useful if it catches a real failure mode early and gives a clear explanation instead of leaving users with vague client-side handshake errors.

Tips for others

If you are building an MCP stdio server:

• never write debug logs to stdout
• use stderr for diagnostics
• test the real command you expect users to run
• check at least one real request after initialization, such as tools/list
• add a CI check so stdout pollution does not accidentally get published

The goal of this project is simple: give MCP developers a fast local check and a CI gate before users hit confusing stdio failures.

Relevant Links

• GitHub repository: https://github.com/1Utkarsh1/mcp-stdio-guard
• npm package: https://www.npmjs.com/package/mcp-stdio-guard
• Documentation: https://github.com/1Utkarsh1/mcp-stdio-guard#readme
• Example gist showing usage/testing: https://gist.github.com/1Utkarsh1/90d7a0f2ea85635e3a209eb1be4970f9