MCPgee
MCPgee
MCPgeeMCPgee

MCP Stdio Guard

v1.0.0•Developer Tools•stable

Catch stdout pollution and handshake failures in MCP stdio servers before clients do.

clidebuggingdeveloper-toolsjson-rpcmcp
Share:
62
Stars
0
Downloads
0
Weekly
0/5
View on GitHub

What is MCP Stdio Guard?

MCP Stdio Guard is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to catch stdout pollution and handshake failures in mcp stdio servers before clients do.

Catch stdout pollution and handshake failures in MCP stdio servers before clients do.

This server falls under the Developer Tools category on MCPgee, the world's largest MCP server directory with 33,000+ servers.

Features

  • Catch stdout pollution and handshake failures in MCP stdio s

Use Cases

Catch stdout pollution and handshake failures in MCP servers.
Debug JSON-RPC issues before they reach clients.
Ensure reliable MCP server communication.
1Utkarsh1

Maintainer

LicenseMIT
Languagejavascript
Versionv1.0.0
UpdatedMay 18, 2026
Statushealthy
Maintenanceactive

Works with

ClaudeOpenAIwindowsmacoslinux
View SourceBrowse All Servers

Installation

Manual Installation

npx mcp-stdio-guard

Configuration

Configuration Details

Config File

claude_desktop_config.json

Performance

Response Metrics

Response Time< 200ms
ThroughputMedium

Resource Usage

Memory UsageLow
CPU UsageLow

How to Set Up and Use MCP Stdio Guard

MCP Stdio Guard is a developer testing and validation tool that wraps MCP stdio servers and checks them for common failure modes before real clients ever connect. It detects stdout pollution (non-JSON data written to stdout that would break the JSON-RPC protocol), handshake failures, malformed tool schemas, and capability mismatches. Developers use it in local testing and CI/CD pipelines to catch these issues early, preventing cryptic client errors and making MCP server development much more reliable.

Prerequisites

  • Node.js 18 or higher installed
  • The MCP server you want to test (must be runnable via a command)
  • npx available (comes with npm 5.2+)
  • No additional API keys or accounts required
1

Run mcp-stdio-guard against your server

Wrap your server command with mcp-stdio-guard using '--' to separate the guard arguments from the server command. The guard will start the server, perform an MCP handshake, and report any issues.

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

Use a built-in validation profile

Profiles bundle common check combinations. The 'registry' profile is designed for servers being submitted to MCP registries; 'ci' profile adds source code scanning and is suited for automated pipelines.

# Registry validation:
npx mcp-stdio-guard --profile registry --json -- node ./server.js

# CI/CD pipeline:
npx mcp-stdio-guard --profile ci --scan src --fail-on-static -- node ./server.js
3

Test specific JSON-RPC requests

Use '--request' to probe specific MCP endpoints after the handshake. The guard validates tools/list, resources/list, and prompts/list, checking for duplicate names, invalid schemas, and missing descriptions.

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

Run stability tests with repeated startups

Use '--repeat' to check that your server initializes consistently across cold and warm starts — useful for catching race conditions or initialization order bugs.

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

Use a JSON config file for complex scenarios

For repeatable test setups with environment variables and safe tool invocations, create a config file. Environment variable values are redacted in JSON output for security.

npx mcp-stdio-guard --config mcp-stdio-guard.config.json

MCP Stdio Guard Examples

Client configuration

mcp-stdio-guard is a development tool, not an MCP server itself. Add it to your MCP client config to wrap and validate a server during development.

{
  "mcpServers": {
    "my-server-guarded": {
      "command": "npx",
      "args": ["mcp-stdio-guard", "--", "node", "./server.js"]
    }
  }
}

Config file with safe tool calls

A mcp-stdio-guard.config.json that runs the server, validates tools/list, and invokes a safe tool to test end-to-end execution.

{
  "command": "node",
  "args": ["./server.js"],
  "env": { "API_TOKEN": "set-in-runner" },
  "profile": "registry",
  "requests": ["tools/list"],
  "safeToolCalls": [
    { "name": "echo", "arguments": { "text": "hello" } }
  ]
}

Troubleshooting MCP Stdio Guard

The guard reports 'stdout pollution detected' even though the server seems fine

Your server (or one of its dependencies) is writing non-JSON content to stdout at startup — often a startup log message, banner, or debug line. Redirect all logging to stderr instead of stdout. Search your code for 'console.log' calls that run before the MCP handshake.

Handshake fails with a timeout error

The server may be taking too long to initialize. Use '--timeout-ms' to increase the timeout (e.g., '--timeout-ms 10000' for 10 seconds). Also check that the server is actually writing a valid MCP initialize response to stdout.

Tools/list validation shows warnings about missing descriptions

Add a 'description' field to every tool definition in your MCP server. While not strictly required by the protocol, descriptions are required by many registries and improve AI model behavior significantly.

Frequently Asked Questions about MCP Stdio Guard

What is MCP Stdio Guard?

MCP Stdio Guard is a Model Context Protocol (MCP) server that catch stdout pollution and handshake failures in mcp stdio servers before clients do. It connects AI assistants to external tools and data sources through a standardized interface.

How do I install MCP Stdio Guard?

Follow the installation instructions on the MCP Stdio Guard GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.

Which AI clients work with MCP Stdio Guard?

MCP Stdio Guard works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.

Is MCP Stdio Guard free to use?

Yes, MCP Stdio Guard is open source and available under the MIT license. You can use it freely in both personal and commercial projects.

Learn More About MCP Servers

Getting Started with MCP

Set up your first MCP server in minutes

MCP Setup Guide

Configure MCP in Claude, Cursor & VS Code

All MCP Tutorials

18+ hands-on guides for developers

MCP FAQ

40+ answers about Model Context Protocol

MCP Stdio Guard Alternatives — Similar Developer Tools Servers

Looking for alternatives to MCP Stdio Guard? Here are other popular developer tools servers you can use with Claude, Cursor, and VS Code.

Ecc

★ 188.2k

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

Javaguide

★ 155.8k

Java 面试 & 后端通用面试指南，覆盖计算机基础、数据库、分布式、高并发、系统设计与 AI 应用开发

Gemini CLI

★ 104.5k

A secure MCP server that wraps the Google Gemini CLI, allowing clients to query Gemini models using local OAuth sessions without requiring an API key. It provides tools for model interaction and diagnostics with built-in protection against command in

Awesome MCP Servers

★ 87.3k

⭐ Curated list of Model Context Protocol (MCP) servers - tools that extend Claude Desktop, Cursor, Windsurf, and other MCP clients with custom capabilities.

MCP Servers

★ 86.0k

Model Context Protocol Servers

CC Switch

★ 77.5k

A cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Gemini CLI & Hermes Agent. Only official website: ccswitch.io

Browse More Developer Tools MCP Servers

Explore all developer tools servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.

Developer ToolsBrowse All Servers

Quick Config Preview

{ "mcpServers": { "mcp-stdio-guard": { "command": "npx", "args": ["-y", "mcp-stdio-guard"] } } }

Add this to your claude_desktop_config.json or .cursor/mcp.json

Read the full setup guide →

Ready to use MCP Stdio Guard?

Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.

33,000+ ServersFree & Open SourceStep-by-Step Guides
Explore All ServersRead Our Guides