Debugging MCP Connection Timeouts and Tool Calling Failures in Claude and Cursor

The top 4 reasons MCP servers fail in Claude Desktop

1. Stdio Pollution (Console Logging): In stdio transport, stdout is reserved strictly for JSON-RPC messages. If your code calls console.log("Starting server..."), the text corrupts the JSON-RPC stream, causing Claude to terminate the connection instantly. Always use console.error() for debug logs.

2. Missing Environment Variables: Claude Desktop does not inherit your full terminal shell profile (.zshrc / .bashrc). Explicitly define environment variables inside claude_desktop_config.json.

3. Schema Type Mismatches: If a tool parameter is marked as number in Zod but the LLM supplies "50" as a string without coercion, the server will reject the call with code -32602.

4. Path Resolution Failures: Using relative paths (e.g. ./server.js) fails because Claude spawns processes from the application root. Always use absolute paths or npx.

Diagnostic Checklist and Verification Script

Use this quick Node.js script to simulate an MCP client and verify that your server outputs valid JSON-RPC handshakes without stdout corruption.

# Test raw MCP handshake over stdio
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2026-07-28","capabilities":{},"clientInfo":{"name":"test-client","version":"1.0.0"}}}' | npx tsx server.ts

Verifying with the Official MCP Inspector

Run npx @modelcontextprotocol/inspector tsx server.ts to open a local web UI where you can inspect every JSON-RPC frame, inspect error codes, and benchmark tool latencies.