"MCP server failed to connect" is the most common complaint in the MCP ecosystem. The error message is almost always useless — a generic failure with no hint about what actually went wrong. Here are the seven real causes, in order of frequency, and how to fix each one.
1. Stdio pollution (the #1 killer)
MCP servers communicate over stdout using newline-delimited JSON-RPC. If anything else writes to stdout — a console.log, a startup banner, a debug print — the client's JSON parser chokes.
Fix: route all logging to stderr. In Node: console.error() instead of console.log(). In Python: use the logging module (it defaults to stderr).
2. Wrong protocol version
Clients negotiate the MCP protocol version during initialize. Servers that hardcode an old version (or don't reply at all) get rejected.
Fix: reply to initialize with the version the client requested, or at minimum 2024-11-05.
3. Missing or broken dependencies
npx servers that fail to download, Python servers with missing pip packages, Node servers with native modules that won't build — all produce the same opaque failure.
Fix: run the server command manually in a terminal first. If it crashes there, it will crash in the client too.
4. Invalid tool schemas
A server can connect successfully but expose zero tools if its input schemas are malformed. Clients silently drop invalid tools.
Fix: validate every tool schema against JSON Schema. Root must be {"type": "object"} with a properties map.
5. Environment variables not set
Servers that need API keys (GitHub, Slack, databases) fail at the first tool call — not at connect time. The connection looks fine, then every call errors.
Fix: check the server's README for required env vars and set them in your client config.
6. Path/working directory issues
Relative paths in server configs resolve against the client's working directory, not the server's. A server that works from your terminal fails from Claude Desktop.
Fix: use absolute paths everywhere in MCP configs.
7. Port conflicts (SSE/HTTP servers)
For remote MCP servers, a port already in use or a firewall blocking the connection produces instant failures.
Fix: check ss -tlnp for conflicts and confirm the port is reachable from the client machine.
The 60-second diagnostic
Instead of guessing, use a tool that shows you the actual JSON-RPC traffic. MCP Workbench connects to any MCP server in your browser and shows every message in both directions — you'll see the exact point where the handshake breaks, the raw error, and the tool list if it connects.
What's the most confusing MCP error you've hit? Drop it in the comments.
Top comments (0)