Why do I get 'spawn ENOENT' when starting an MCP server?

Spawn ENOENT indicates the client cannot find the executable (like npx, uvx, or node) in your system PATH. Specify the absolute binary path or ensure the runtime is in your system PATH.

Why does Claude Desktop show 'stdio transport closed'?

Stdio transport closed means the server process crashed during startup. Check Node/Python versions, run the command in a terminal to see stderr logs, or check for missing API keys.

Diagnostic Engine

Model Context Protocol Error Decoder and Solutions

Diagnose and resolve connection drops, handshake failures, and subprocess crashes across Claude Desktop, Cursor, and Windsurf.

Full Error Decoder on mcp-codex.com → Report Unsolved Issue

Select an error message to diagnose:

DIAGNOSTIC

spawn ENOENT: Executable Not Found

The MCP client cannot locate the binary specified in "command" (usually "npx", "uvx", "node", or "python") in your system PATH.

Recommended Resolution Steps:

1. Specify absolute path to executable (e.g. /usr/local/bin/npx or C:\Program Files\nodejs\npx.cmd).
2. Verify Node.js or uv is installed in your terminal environment.
3. Restart Claude Desktop or Cursor after updating your system PATH.

View Detailed Guide on mcp-codex.com →

Best Practices

4 Golden Rules of MCP Debugging

Follow these systematic checks whenever an MCP server fails to connect:

1️⃣

Run Directly in Terminal

Copy the command and args from your config and paste them into a clean terminal session. If it fails with a traceback there, it will never work inside Claude or Cursor.

2️⃣

Check Absolute Paths

GUI apps on macOS and Windows do not always inherit your shell's ~/.zshrc or $PATH. Use absolute paths to node, npx, or uvx.

3️⃣

Verify Environment Variables

Many servers fail silently without required API tokens (like GITHUB_PERSONAL_ACCESS_TOKEN or database credentials). Always verify the env object in your config.

4️⃣

Inspect Client Logs

Inspect the client developer logs. For Claude Desktop, open Developer > Toggle Developer Tools to inspect the console for detailed JSON-RPC handshake errors.