mcp-stdio-guard

mcp-stdio-guard is a robust tool designed to monitor and enforce protocol compliance in MCP (Model Context Protocol) stdio servers by catching stdout pollution and handshake failures before they impact client performance. It serves as an essential safeguard, initiating a real MCP handshake process, optionally sending post-initialization requests such as tools/list, and validating every stdout frame to ensure a clean communication pipeline.

Key Features

• Protocol Compliance: Conforms to the latest MCP specifications, ensuring that servers only transmit JSON-RPC messages over stdout and adhere to the required lifecycle phases of initialization and notification.
• Real-Time Monitoring: Detects issues like stray console.log messages or improper stdout outputs in real-time, thereby minimizing runtime errors and confusion for clients.
• Static Source Scanning: Checks source code for potentially harmful stdout writes to prevent issues before they occur.

Use Cases

To utilize the mcp-stdio-guard, run your MCP server with the following command:

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

To execute a specific MCP operation post-initialization:

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

The tool can also scan your source code for examples of risky stdout uses:

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

Monitoring and Output

For CI purposes, the guard provides JSON-formatted output that details the results of the checks, featuring status indicators for initialization, stdout quality, JSON-RPC messaging, and operation responses. This structured output helps maintain clear visibility over server performances and compliance with the intended protocol.

Example Output

• Passing server:

PASS MCP stdio guard
initialize: ok
frames: 2 stdout / 0 invalid
stderr: 0 lines
protocol: 2025-11-25
request: tools/list responded

• Polluted stdout:

FAIL MCP stdio guard
initialize: ok
frames: 2 stdout / 1 invalid
stderr: 0 lines
protocol: 2025-11-25
request: tools/list responded
[error] stdout-non-json: stdout line 1 is not JSON-RPC: "server starting..."

Through its detailed checks and validations, mcp-stdio-guard ensures that developers can maintain high-quality and reliable interactions between their MCP servers and clients, reducing the risk of errors due to improper stdout handling.