Catalog My learning Blog
MCP Setup Guides: Cursor, Codex, Gemini CLI and Top Servers · Phase 3 · Lesson 14 · 5 min read

MCP Server Not Connecting? Troubleshooting Guide

On this page
  1. Start here: run the command yourself
  2. 1. "spawn npx ENOENT" or "command not found"
  3. 2. It works on macOS but not on Windows
  4. 3. It times out the first time, then works
  5. 4. Environment variable didn't reach the server
  6. 5. The server shows as disabled or never loads
  7. 6. OAuth never finishes
  8. 7. Connected, but tool calls fail with "invalid JSON" or the server drops
  9. 8. Connected, but the agent ignores the tools
  10. Get the logs
  11. Test the server without any AI tool
  12. 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:

Shell
npx -y @playwright/mcp@0.0.84

A 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:

Code
"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:

YAML
"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:

ToolHow to raise the startup timeout
Claude CodeMCP_TIMEOUT=30000 claude (milliseconds)
Codex CLIstartup_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.

ToolVariable syntax in config
Claude Code (.mcp.json)${VAR} or ${VAR:-default}
Cursor${env:VAR}
Gemini CLI$VAR, ${VAR} or ${VAR:-default}
Codex CLIAn 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 trust in the session.
  • Claude Code project approval. Servers from a project's .mcp.json need your approval the first time. If you declined, run claude mcp reset-project-choices and 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:

ToolCommand
Claude Code/mcp, select the server, then Authenticate. Or claude mcp login <name>
Codex CLIcodex mcp login <name> (and codex mcp logout <name> to reset)
Cursor, ZedToggle 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:

ToolWhere the logs are
Claude CodeStart with claude --debug=mcp, and check /mcp for the server's status
CursorOutput panel (Cmd+Shift+U), then MCP Logs in the dropdown
Codex CLIcodex mcp list for status, then codex mcp get <name> for its settings
Gemini CLIgemini mcp list for status, /mcp inside a session for tools
JetBrainsHelp, 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:

Shell
npx @modelcontextprotocol/inspector --cli npx -y @playwright/mcp@0.0.84 --method tools/list

If 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.