MCP Server Not Connecting? Troubleshooting Guide
On this page
- Start here: run the command yourself
- 1. "spawn npx ENOENT" or "command not found"
- 2. It works on macOS but not on Windows
- 3. It times out the first time, then works
- 4. Environment variable didn't reach the server
- 5. The server shows as disabled or never loads
- 6. OAuth never finishes
- 7. Connected, but tool calls fail with "invalid JSON" or the server drops
- 8. Connected, but the agent ignores the tools
- Get the logs
- Test the server without any AI tool
- Check yourself
Start here: run the command yourself
Before you change any config, copy the exact command and args from your config and run them in a terminal:
npx -y @playwright/mcp@0.0.84A working stdio server prints nothing, or a line or two of logs, and then waits for input. That's normal: it's waiting for a client to talk to it. Press Ctrl+C to stop it. If you see an error instead, you've found your problem, and it has nothing to do with your AI tool.
If the command works in the terminal but not in your tool, the difference is the environment your tool starts it in. Most of this guide is about that difference.
1. "spawn npx ENOENT" or "command not found"
Cause: your tool can't find npx, uvx, docker or whatever the command is. This happens most with desktop apps such as Claude Desktop, Cursor or a JetBrains IDE launched from the Dock or Start menu. They don't load your shell profile, so a Node installed with nvm, fnm or Volta isn't on their PATH.
Fix: use the full path. Find it with which npx (macOS and Linux) or where npx (Windows), and put that in command:
"command": "/Users/you/.nvm/versions/node/v24.15.0/bin/npx"Starting the app from a terminal also works for a quick test, because it then inherits your shell's PATH.
2. It works on macOS but not on Windows
Cause: on Windows, npx is a npx.cmd script, and some clients can't launch .cmd files directly.
Fix: start it through cmd:
"command": "cmd",
"args": ["/c", "npx", "-y", "chrome-devtools-mcp@1.12.0"]3. It times out the first time, then works
Cause: the first run of npx -y package or uvx package downloads it, and that can take longer than the client's startup timeout.
Fix: run the command once in a terminal so it's cached, then raise the timeout:
| Tool | How to raise the startup timeout |
|---|---|
| Claude Code | MCP_TIMEOUT=30000 claude (milliseconds) |
| Codex CLI | startup_timeout_ms = 30_000 in the server's table in config.toml |
| Gemini CLI | --timeout 30000 on gemini mcp add, or a timeout value in settings.json |
4. Environment variable didn't reach the server
Cause: each tool has its own syntax for variables in config files, and an unset variable is often passed through as literal text. A server that receives the string $GITHUB_PAT as a token will answer 401 on every call.
| Tool | Variable syntax in config |
|---|---|
Claude Code (.mcp.json) | ${VAR} or ${VAR:-default} |
| Cursor | ${env:VAR} |
| Gemini CLI | $VAR, ${VAR} or ${VAR:-default} |
| Codex CLI | An env table, or bearer_token_env_var for remote servers |
| VS Code | ${input:name} to prompt once and store the value securely |
Fix: use the right syntax for your tool, export the variable in the shell or profile your tool starts from, then restart the tool completely. Desktop apps only read environment variables when they launch.
5. The server shows as disabled or never loads
Two features do this on purpose:
- Gemini CLI folder trust. In an untrusted folder, every MCP server is disabled, including user-level ones. Run
/permissions trustin the session. - Claude Code project approval. Servers from a project's
.mcp.jsonneed your approval the first time. If you declined, runclaude mcp reset-project-choicesand start Claude Code again.
Also check the obvious: the server might just be toggled off in Cursor's Customize panel, or with gemini mcp disable or /mcp disable.
6. OAuth never finishes
Cause: the browser sign-in didn't open, was closed, or the stored login expired.
Fix: run the sign-in again yourself:
| Tool | Command |
|---|---|
| Claude Code | /mcp, select the server, then Authenticate. Or claude mcp login <name> |
| Codex CLI | codex mcp login <name> (and codex mcp logout <name> to reset) |
| Cursor, Zed | Toggle the server off and on, then use one of its tools |
7. Connected, but tool calls fail with "invalid JSON" or the server drops
Cause: in the stdio transport, standard output is reserved for protocol messages. A server that prints logs or a banner to stdout corrupts the stream.
Fix: if it's your own server, send all logging to standard error (console.error in Node, print(..., file=sys.stderr) in Python). If it's a third-party server, check for a quiet or log-level flag, and report it upstream.
8. Connected, but the agent ignores the tools
Cause: too many tools, or tool descriptions that don't match how you phrase requests.
Fix: turn off servers you don't need in this project, and limit big servers to the tools you use (GitHub toolsets, --include-tools in Gemini CLI). Name the tool or server in your prompt the first few times, for example "use the GitHub server to list my open pull requests".
Get the logs
When none of the above fits, read the actual error:
| Tool | Where the logs are |
|---|---|
| Claude Code | Start with claude --debug=mcp, and check /mcp for the server's status |
| Cursor | Output panel (Cmd+Shift+U), then MCP Logs in the dropdown |
| Codex CLI | codex mcp list for status, then codex mcp get <name> for its settings |
| Gemini CLI | gemini mcp list for status, /mcp inside a session for tools |
| JetBrains | Help, Show Log, then the mcp folder |
Test the server without any AI tool
The MCP Inspector talks to a server directly, so you can tell a server problem from a client problem. Its CLI mode lists a server's tools in one command:
npx @modelcontextprotocol/inspector --cli npx -y @playwright/mcp@0.0.84 --method tools/listIf the Inspector lists the tools but your AI tool doesn't, the problem is in your tool's config. If the Inspector fails too, the problem is the server, its command or its environment. Run it without --cli for a web interface where you can call tools by hand.
Check yourself
Claude Desktop doesn't get your shell's PATH. Put the full path to npx, from which npx, in command.
That GITHUB_PAT is exported in the shell you start Gemini CLI from. If it's unset, the literal text $GITHUB_PAT is sent as the token.
Run the server through the MCP Inspector. If the Inspector can list its tools, the server is fine and the client config is wrong.