MCP server won't connect or misbehaves: fix

By mcp-guide · 0 stars

### Check first

1. Quit the host fully and reopen it; most read config only at startup.
2. Validate the JSON. Look for trailing commas and unescaped Windows backslashes.
3. Open the MCP status: `/mcp` (Claude Code), "MCP: List Servers" (VS Code), connectors menu (Claude apps), MCP settings (Cursor).
4. Read the log.
5. Run the server in MCP Inspector to tell a server problem from a host problem.

| Host | Logs |
|---|---|
| Claude Desktop (macOS) | `~/Library/Logs/Claude/mcp.log`, `mcp-server-NAME.log` |
| Claude Desktop (Windows) | `%APPDATA%\Claude\logs\` |
| Claude Code | `/mcp`; `claude --debug` for verbose output |
| Cursor | Output panel > "MCP Logs" |
| VS Code | "MCP: List Servers" > Show Output |

### Runbook

| Symptom | Likely cause | Fix |
|---|---|---|
| Local server never appears | Bad JSON, relative path, no restart | Fix JSON, use absolute paths, restart fully |
| `spawn npx ENOENT` or command not found | GUI host can't see your shell PATH (macOS, nvm, asdf) | Absolute path to `npx`/`uvx`/`node`, or set `PATH` in `env` |
| Windows error mentioning `${APPDATA}` | Variable not expanded | Put the expanded `APPDATA` path in the server's `env` |
| Server starts, then dies | Missing API key env var; wrong Node or Python version | Run the exact command in a terminal and read the error |
| Parse errors or garbled output (stdio) | Server logs to stdout | Log to stderr; stdout carries JSON-RPC only |
| Works locally, fails in claude.ai or ChatGPT | Server on localhost or a private network | Deploy publicly or tunnel |
| 404 or 405 on a URL that used to work | `/sse` endpoint retired | Use the vendor's `/mcp` endpoint |
| OAuth loop or "invalid client" | Stale client registration; redirect URI mismatch | `claude mcp logout`, or remove and re-add; check allowed redirect URIs |
| `403 insufficient_scope` | Token lacks the tool's scope | Reconnect and approve the scope; escalate to your admin if you can't |
| Tools listed but never used | Vague descriptions, too many tools, tool switched off | Name the server in your prompt; disable unneeded tools |
| Tool result truncated | Output over the host limit | Claude Code: raise `MAX_MCP_OUTPUT_TOKENS`; paginate in the server |
| Startup times out | First-run package download | Install the package globally, or raise `MCP_TIMEOUT` (Claude Code) |
| ChatGPT shows old tools | Cached metadata | Refresh the plugin in ChatGPT Plugins; new chat |
| Teammate doesn't see a project server | Not approved yet | They approve the `.mcp.json` server in Claude Code |
| Custom server breaks with a newer host | Old SDK vs stateless 2026-07-28 spec | Upgrade the server's SDK first |

### MCP Inspector

Needs Node.js 22.19+ for Inspector 2.x. Also connects to remote URLs and walks through OAuth step by step.

~~~bash
# Web UI against a local stdio server
npx @modelcontextprotocol/inspector node build/index.js

# CLI mode, for scripts
npx @modelcontextprotocol/inspector --cli node build/index.js

# Python server run with uv
npx @modelcontextprotocol/inspector uv --directory path/to/server run my-server
~~~