Debugging MCP Servers: A Developer Guide
Diagnose, debug, and resolve MCP server issues: handle stdio stream corruption, use the MCP Inspector, interpret JSON-RPC error codes, and audit telemetry.
Generate & Validate Multi-Client MCP Config
One-click export with environment variables & path locators for Claude Desktop, Cursor, Windsurf, and OpenAI Codex CLI.
Debugging MCP Servers: A Developer Guide
Building Model Context Protocol (MCP) servers unlocks autonomous agent workflows, but debugging them introduces a unique engineering hurdle: MCP servers run as isolated child processes communicating over strict JSON-RPC 2.0 message pipes.
When a standard web app fails, errors print visibly to terminal logs or browser developer tools. When an MCP server fails, the client host (Claude Desktop, Cursor, Codex CLI) often exhibits silent disconnections, unresponsive tool loops, or vague Process exited with code 1 messages.
This guide provides an end-to-end troubleshooting methodology for diagnosing, debugging, and hardening MCP servers in both TypeScript and Python.
1. The Number One Bug: Standard Stream (stdio) Poisoning
The overwhelming majority of MCP crashes during local development stem from stdio protocol pollution.
The Mechanism
In stdio transport mode, stdin and stdout are strictly reserved for newline-delimited JSON-RPC framing:
- ▸Client -> Server (
stdin): JSON-RPC requests (tools/list,tools/call) - ▸Server -> Client (
stdout): JSON-RPC responses ({ "jsonrpc": "2.0", "result": ... })
If your server code—or any third-party library imported by your server—emits plain text, debug logs, or deprecation notices to stdout via console.log() or print(), the client's JSON parser chokes:
SyntaxError: Unexpected token 'D', "Database c"... is not valid JSONThe host immediately terminates the transport session, severing all agent tool access.
The Fix: Standardize on stderr
All human logging, diagnostic tracing, and error telemetry must be routed exclusively to stderr.
TypeScript / Node.js
// FATAL: Corrupts the stdio JSON-RPC stream
console.log("Connecting to PostgreSQL...");
// CORRECT: stderr is safely captured by client host logs
console.error("[MCP-Server] Connecting to PostgreSQL...");
process.stderr.write("[DEBUG] Fetching user records\n");To guard against rogue third-party packages writing to stdout, redirect global output early in your server entrypoint:
// server.ts (top of file)
const originalStdoutWrite = process.stdout.write.bind(process.stdout);
// Override console.log to route to stderr
console.log = (...args: unknown[]) => {
console.error("[Redirected stdout]", ...args);
};Python / FastMCP
import sys
import logging
# FATAL: Corrupts stdio stream
print("Server initialized")
# CORRECT: Direct print to stderr
print("[DEBUG] Server initialized", file=sys.stderr)
# RECOMMENDED: Configure standard logging to stderr
logging.basicConfig(
stream=sys.stderr,
level=logging.INFO,
format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
)
logger = logging.getLogger("mcp-server")
logger.info("Server listening safely")2. Interactive Testing with the MCP Inspector
Never test new MCP servers directly inside heavy LLM desktop clients. Use the official MCP Inspector, an interactive web harness designed to inspect raw JSON-RPC traffic, discover tools, and trigger manual tool invocations without burning API tokens.
Launching the Inspector
Run the inspector directly via npx:
# Testing a Node.js / TypeScript MCP server
npx @modelcontextprotocol/inspector node dist/index.js
# Testing with tsx during live development
npx @modelcontextprotocol/inspector npx tsx src/index.ts
# Testing a Python server (uv-managed)
npx @modelcontextprotocol/inspector uv run python server.pyPassing Environment Variables and Arguments
If your server requires credentials, pass arguments and flags after --:
npx @modelcontextprotocol/inspector node dist/index.js --db-path ./data.dbTo inject environment variables:
DATABASE_URL="postgres:///dev" npx @modelcontextprotocol/inspector node dist/index.jsWhat to Verify in Inspector
- ▸Initialize Handshake: Look at the notification stream. Confirm negotiated protocol version (
2024-11-05) and declared capabilities (tools,resources,prompts). - ▸Tools List: Check the Tools tab. Verify parameter schemas, required attributes, and descriptions.
- ▸Manual Tool Execution: Run tool calls with valid and boundary inputs. Validate that output returns cleanly formatted
contentblocks. - ▸Notifications: Verify whether dynamic notifications (such as resource updates) fire without unhandled rejections.
3. Attaching Live Debuggers (Breakpoints and Step-Through)
When printf-debugging to stderr is insufficient, attach full IDE debuggers with step-through execution and memory inspection.
Debugging TypeScript in VS Code / Cursor
Add a dedicated launch configuration to .vscode/launch.json:
{
"version": "0.2.0",
"configurations": [
{
"name": "Debug MCP Server (Node)",
"type": "node",
"request": "launch",
"runtimeExecutable": "npx",
"runtimeArgs": ["tsx", "src/index.ts"],
"console": "internalConsole",
"outputCapture": "std",
"env": {
"DEBUG": "true",
"NODE_ENV": "development"
}
},
{
"name": "Attach to MCP Inspector Process",
"type": "node",
"request": "attach",
"port": 9229,
"restart": true
}
]
}To run your server through the MCP Inspector with a Node debugger listening on port 9229:
npx @modelcontextprotocol/inspector node --inspect=9229 dist/index.jsNow click Attach to MCP Inspector Process in your IDE to hit breakpoints inside tool handlers in real time.
Debugging Python MCP Servers with debugpy
In your Python server, you can dynamically attach debugpy:
import debugpy
import sys
# Enable remote debugging if DEBUG_MODE is set
if "--debug" in sys.argv:
debugpy.listen(("localhost", 5678))
print("[DEBUG] Waiting for debugger attach on port 5678...", file=sys.stderr)
debugpy.wait_for_client()Attach to port 5678 using the standard Python VS Code debug configuration.
4. Understanding MCP JSON-RPC Errors
Errors in MCP operate on two distinct levels: Protocol-level errors and Tool-execution errors. Conflating them breaks agent self-healing.
Protocol Errors vs Tool Errors
| Type | When to Use | Effect on Client |
|---|---|---|
JSON-RPC Error Code (-32xxx) | Protocol violation (malformed JSON, unknown method, unparseable payload) | Client treats session or request as critically broken |
Tool Error (isError: true) | Business logic failure (record not found, rate limit hit, invalid query) | Agent reads error message and attempts alternative approach |
Standard JSON-RPC 2.0 Error Codes
When writing custom low-level dispatchers, adhere to standardized error codes:
export const McpErrorCodes = {
ParseError: -32700, // Invalid JSON received by server
InvalidRequest: -32600, // Payload is not a valid Request object
MethodNotFound: -32601, // Method does not exist / not declared
InvalidParams: -32602, // Tool arguments failed schema validation
InternalError: -32603 // Unhandled internal server exception
} as const;Proper Tool Error Handling Pattern
Never let an internal database timeout or filesystem exception throw an unhandled promise rejection. Wrap handlers to return a structured error block:
server.setRequestHandler(CallToolRequestSchema, async (request) => {
const { name, arguments: args } = request.params;
if (name === "query_records") {
try {
const records = await db.query(args.filter);
return {
content: [
{
type: "text",
text: JSON.stringify(records, null, 2)
}
]
};
} catch (err: any) {
// Return tool failure so the LLM can adjust parameters or self-heal
return {
isError: true,
content: [
{
type: "text",
text: `Database query failed: ${err.message}. Please refine your search filter.`
}
]
};
}
}
throw new McpError(
ErrorCode.MethodNotFound,
`Unknown tool requested: ${name}`
);
});5. Client Log Locations and Forensic Auditing
When a server works in the MCP Inspector but fails in your agent host, check client execution logs.
Claude Desktop Logs
Claude logs every child process invocation and captures stderr:
- ▸macOS:
~/Library/Logs/Claude/mcp.logand~/Library/Logs/Claude/mcp-server-{name}.log - ▸Windows:
%APPDATA%\Claude\logs\mcp.logand%APPDATA%\Claude\logs\mcp-server-{name}.log - ▸Linux:
~/.config/Claude/logs/mcp.log
Tailing live logs during testing:
# macOS
tail -f ~/Library/Logs/Claude/mcp*.log
# Windows PowerShell
Get-Content -Path "$env:APPDATA\Claude\logs\mcp.log" -Wait -Tail 30Cursor IDE Logs
In Cursor:
- ▸Open the Command Palette (
Ctrl+Shift+P/Cmd+Shift+P). - ▸Type Output: Focus on Output View.
- ▸Select MCP or Cursor Tab from the output dropdown channel.
- ▸Review the raw child-process spawn command and environment variables.
OpenAI Codex CLI Logs
Codex CLI outputs process traces when launched with verbose debugging:
# Run codex with full transport tracing enabled
DEBUG=mcp:* codex exec "Inspect recent logs"6. Common Failure Modes and Solutions
Issue A: "Command not found: npx / node / uv"
- ▸Cause: GUI applications (like Claude Desktop on macOS) do not inherit shell profile environment variables (
.zshrc,.bash_profile,PATH). System PATH in GUI apps defaults to/usr/bin:/bin:/usr/sbin:/sbin. - ▸Solution: Use absolute paths for the command binary in client configs:
{
"mcpServers": {
"my-server": {
"command": "/Users/username/.nvm/versions/node/v20.10.0/bin/node",
"args": ["/Users/username/projects/my-server/dist/index.js"]
}
}
}Issue B: "Zod Schema Type Coercion Mismatch"
- ▸Cause: LLMs occasionally send numbers as strings (
"limit": "10"instead of10) or pass boolean flags as"true". - ▸Solution: Use
z.coercein Zod schemas:
const QueryParamsSchema = z.object({
query: z.string().min(1),
limit: z.coerce.number().int().positive().default(20),
includeArchived: z.coerce.boolean().default(false)
});Issue C: Zombie MCP Processes
- ▸Cause: When client hosts restart or crash, spawned child processes can remain alive in the background holding file locks or ports.
- ▸Solution: Handle
SIGTERMandSIGINTcleanly:
const cleanup = async () => {
console.error("[MCP] Terminating server cleanly...");
await server.close();
process.exit(0);
};
process.on("SIGINT", cleanup);
process.on("SIGTERM", cleanup);Summary Checklist for Production MCP Servers
Before deploying your server to production clients:
- ▸ Audit stdout: Ensure zero calls to
console.logor unformattedprint(). All logging routes tostderr. - ▸ Test with Inspector: Verified
initialize, tool lists, and manual invocations in@modelcontextprotocol/inspector. - ▸ Schema Coercion: Handled stringified numbers and booleans in parameter schemas.
- ▸ Graceful Errors: Handled tool execution errors with
isError: trueinstead of crashing the process. - ▸ Absolute Paths: Configured absolute binary paths for GUI client compatibility.
- ▸ Signal Handling: Implemented
SIGINTandSIGTERMhandlers to eliminate orphaned processes.
7. External Citations and Official Documentation
- ▸Model Context Protocol Specification (opens in a new tab) — Official standard for JSON-RPC 2.0 messages, transport mechanics, and error codes.
- ▸Model Context Protocol Inspector Repository (opens in a new tab) — Interactive web-based testing harness for inspecting MCP servers without an LLM host.
- ▸JSON-RPC 2.0 Specification (opens in a new tab) — Official specification for error codes, request objects, and response envelopes.
- ▸Zod TypeScript Schema Validation (opens in a new tab) — Schema validation library utilized for safe argument parsing and type coercion.
Build your full agent toolstack in the Visual Generator
Combine verified MCP servers with databases, search APIs, and memory graphs in a single configuration file.
Did this setup guide work with your AI host?
Help test this configuration across Claude, Cursor, and Codex CLI. Be the first to report:
Written by Rad Tome
Lead AI Systems Architect & Maintainer, MCP Codex
Specializing in Model Context Protocol (MCP) integrations, autonomous AI agent orchestration, and distributed developer toolchains. Researches and benchmarks production MCP client-server architectures across OpenAI Codex, Claude, and Cursor.
Related Guides
OpenCode Free AI Agent Guide
Guide to running OpenCode coding agent completely free without API keys using Zen free tier, local LLMs, and OAuth accounts.
Dev ToolsSelf-Correcting Verification Loops in Agents
Build robust self-correcting /loop verification harnesses for AI agents using Test-Driven Agent Development, dual-agent critics, and MCP test sandboxes.
Dev ToolsAutomated Doc Verification Loops with Claude CLI
Build automated documentation verification loops with Claude CLI and MCP. Validate code snippets, test tool schemas, and sync SDK docs in CI/CD. Verified.