MCP stdio diagnostics

A tiny diagnostic kit for MCP servers that communicate over stdio.

It helps separate three failure classes that are often conflated in client UIs:

1. stdout contains text that is not JSON;
2. stdout contains JSON that is not a JSON-RPC 2.0 object;
3. the server process fails before protocol exchange starts.

This repository does not claim that stdout logging is the universal cause of MCP -32700 Parse Error. Use it as a first-pass transport check, then continue with client logs, SDK/runtime versions, startup paths, and protocol-version checks.

Quick start

Validate a captured stdout stream:

python3 validate_stdout.py fixtures/clean.jsonl
python3 validate_stdout.py fixtures/polluted.log
python3 validate_stdout.py fixtures/invalid-jsonrpc.jsonl

Expected results:

• clean.jsonl exits 0;
• polluted.log exits non-zero and identifies the first non-JSON line;
• invalid-jsonrpc.jsonl exits non-zero because the JSON object is not JSON-RPC 2.0.

Run the regression check:

bash test.sh

Why this exists

For MCP stdio, protocol messages and application diagnostics must not be treated as the same output channel. A fast way to narrow the problem is to capture stdout and stderr separately, validate the stdout framing, and only then move up to MCP lifecycle/tool semantics.

This repository intentionally keeps the validator dependency-free so it can be copied into a failing environment before changing the application.

Related guide

The full troubleshooting guide covers -32700 Parse Error, Tool list failed, spawn ENOENT, stdout/stderr separation, JSON-RPC structure, client/runtime differences, and protocol-version boundaries:

• English: https://www.xbstack.com/en/ai/mcp-json-rpc-parse-error/?utm_source=github&utm_medium=referral&utm_campaign=mcp_parse_error_fix&utm_content=repository_readme
• 中文: https://www.xbstack.com/ai/mcp-json-rpc-parse-error/?utm_source=github&utm_medium=referral&utm_campaign=mcp_parse_error_fix&utm_content=repository_readme_zh

Primary references

• MCP transport specification: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports
• JSON-RPC 2.0 specification: https://www.jsonrpc.org/specification
• MCP TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk
• MCP Python SDK: https://github.com/modelcontextprotocol/python-sdk

License

MIT