Setting up MCP servers can be frustrating. Here are the top 5 errors developers encounter and how to solve them.
1. “Connection Refused” / “ENOENT”
Symptoms: The tool icon doesn’t appear, or clicking it shows a red error.
Cause: The Host cannot find the executable command (e.g., npx, python, uvx).
Fix: Use absolute paths.
- Bad:
"command": "python" - Good:
"command": "/usr/bin/python3" - Why: MacOS apps launched via UI (Finder/Dock) often don’t inherit your shell’s
$PATH.
2. “Invalid JSON”
Symptoms: Claude Desktop fails to start or resets to default. Cause: A trailing comma after the last item in a list or object. Fix: Use a JSON linter or Vibe Manager (which validates JSON automatically).
3. “Access Denied” (FileSystem)
Symptoms: The AI says “I cannot read that file.”
Cause: The MCP FileSystem server is sandboxed. It can only read directories you explicitly listed in the args.
Fix: Add the path to your config args.
args: ["/Users/me/projects/my-new-app"]
4. “Timeout” or “Hanging”
Symptoms: The AI says “Thinking…” forever. Cause: The MCP server crashed silently or is waiting for input. Fix: Check the logs.
- Claude Logs:
tail -f ~/Library/Logs/Claude/mcp.log - Ensure your server isn’t trying to ask for interactive user input (it must run headless).
5. “Environment Variable Missing”
Symptoms: “Authentication failed” or “API key not found.”
Cause: You set the API key in your .zshrc, but the GUI app doesn’t see it.
Fix: You must define the environment variable inside the MCP config file itself.
"env": {
"GITHUB_TOKEN": "ghp_..."
}Summary
Most issues boil down to Paths and Environment Variables. Since GUI apps run in a different context than your Terminal, you need to be explicit about everything.