Troubleshooting Common MCP Server Errors

A Diagnostic Playbook

Most "my MCP server won't connect" reports fall into one of five buckets. Work through them in order — each step is cheap and rules out a category.

1. JSON syntax errors

The client refuses to load a malformed config and silently disables MCP. Validate the file:

# macOS / Linux
python3 -m json.tool < ~/Library/Application\ Support/Claude/claude_desktop_config.json

Or paste it into the JSON formatter — it highlights the exact failing character. Common culprits: trailing commas, unescaped backslashes (see Windows paths), and smart quotes from copy-pasting Markdown.

2. ENOENT on spawn ('npx' not found)

The client's environment doesn't include the binary on PATH. Check:

which npx    # macOS / Linux
where.exe npx   # Windows

If it works in your terminal but not in the client, the GUI app started before your shell rc files did. Either:

• Reinstall Node from the official installer (system-wide PATH).
• Use absolute paths in command: "command": "/usr/local/bin/npx".

3. Missing or wrong env vars

[error] BRAVE_API_KEY is not set

Check the per-server log file for the exact var name. Copy the name into your config — the server will fail loudly if you typo it.

For tokens that "look right" but get 401:

• GitHub: regenerate via github-with-token; fine-grained tokens expire by default.
• Brave: ensure the key starts with BSA_ and you're under the monthly quota.

4. Path issues

For filesystem: confirm the path exists and is readable by the user the client runs as:

ls -la /Users/you/Documents

If it's a symlink or network mount, dereference to the real path.

5. Silent crashes after connect

The server initializes but exits when the model calls a tool. Tail the log:

tail -F ~/Library/Logs/Claude/mcp-server-*.log

A stack trace usually appears. If the server is npm-distributed, check its GitHub issues — newer versions sometimes break against older client versions and vice versa. Pin a known-good version:

"args": ["-y", "@modelcontextprotocol/server-github@2024.10.7"]

Last resort: minimal config

If nothing works, reduce the config to a single filesystem server pointing at /tmp and confirm that loads. If even that fails, the issue is environmental (PATH, permissions, JSON parsing) rather than per-server.