MCP server not connecting? Read the logs first — here's how
Symptom: The client shows the server as failed, disconnected, or perpetually 'connecting', and your tools never become available.
Short answer
A connection failure is almost never mysterious — the client log names the cause. Find the MCP log, read the last 20 lines, and you'll see one of four things: the command wasn't found, a dependency is missing, the transport is wrong (stdio vs remote), or the server crashed on startup because of a missing env var.
Why it happens, ranked by how often it's the real cause
1. The command or package can't be found
The #1 log line: 'command not found' or 'npm ERR! could not determine executable'. The runner (npx/uvx/node) isn't on the app's PATH, or the package name is wrong.
Fix: Run the exact command from your config in a terminal. If it fails there too, fix the package name; if it works in terminal but not the app, use an absolute path to the runner.
2. Crash on startup from a missing/empty env var
Many servers exit immediately if a required API key or connection string is absent — the log shows a stack trace ending in 'undefined' or 'missing required environment variable'.
Fix: Fill every key in the config's "env" block. Placeholders like <your-api-key> must be replaced with real values.
3. Wrong transport (stdio config for a remote server, or vice versa)
Pasting a stdio command for a server that's actually a hosted URL (or wrapping a URL in mcp-remote when it shouldn't be) produces an immediate handshake failure.
Fix: Check the server's transport. Local = command + args; remote = a url (Claude Desktop bridges remote via the mcp-remote proxy). Each server page here shows the correct one per client.
4. Node/Python version too old
Some servers need Node 18+ or a recent Python; an old runtime throws a syntax or import error on load.
Fix: Upgrade the runtime, or pin the runner to a newer version.
Fix it step by step
- 1Open the MCP log (Claude: ~/Library/Logs/Claude/mcp-server-*.log; Cursor/Windsurf: the MCP/Output panel).
- 2Read the last 20 lines — the error is almost always there verbatim.
- 3Reproduce by running the config's exact command in your terminal; fix whatever it complains about.
- 4Confirm every required env var has a real value (no leftover placeholders).
- 5Verify the transport matches the server (local command vs remote url).
Still stuck?
If the command runs cleanly in a terminal but the client still won't connect, it's an environment gap — use the absolute path to the runner and hard-code any env vars in the config rather than relying on your shell profile.
FAQ
Where are the MCP server logs?
Claude Desktop: ~/Library/Logs/Claude/mcp-server-*.log (macOS). Cursor and Windsurf surface MCP logs in their Output/MCP panel. The log almost always states the exact reason a server failed to connect.
Why does my MCP server keep disconnecting?
Usually a crash-on-start loop: the server exits because of a missing env var or bad argument, the client retries, and it looks like it keeps disconnecting. The log shows the underlying exit error.