Troubleshooting MCP servers

When an MCP server fails, the message you see, such as "Connection closed" or a red status dot, is rarely the cause. It is the last thing that happened. This guide gives you a quick triage that finds the failing step, the log location for each major client, and the fix for each common symptom.

Triage in four steps

Starting a server takes four steps: the client reads its config, starts the process or opens the URL, completes the MCP handshake, and lists the tools. Work through them in order.

1. Run the exact command in a terminal. Copy command and args from your config and run them. A healthy stdio server prints nothing and waits for input. That looks like a hang, and it's correct. If it prints an error, you have your answer.

2. Test outside your client with the MCP Inspector. Replace node path/to/server.js with your server's command. If the Inspector lists tools and your client doesn't, the server is fine and the problem is your client's environment or config file.

   npx @modelcontextprotocol/inspector --cli node path/to/server.js --method tools/list
   

3. Read the client's log. Locations are below.

4. Check the config file. The right file, the right top-level key, valid JSON, and a full restart of the client.

Where the logs are

• Claude Desktop: ~/Library/Logs/Claude on macOS and %APPDATA%\Claude\logs on Windows. mcp.log records connection events, and mcp-server-NAME.log holds each server's stderr.
• Claude Code: claude mcp list health-checks every server, and claude mcp get NAME shows why one failed. Inside a session, /mcp shows status.
• Cursor: open the Output panel and choose MCP Logs from the dropdown.
• VS Code: run MCP: List Servers from the Command Palette, pick the server and choose Show Output.

The server doesn't show up

The client never loaded the entry. Check these in order:

• The wrong file. Each client has its own: claude_desktop_config.json for Claude Desktop, .mcp.json or ~/.claude.json for Claude Code, .cursor/mcp.json or ~/.cursor/mcp.json for Cursor, and .vscode/mcp.json for VS Code. The client pages list the paths for every app.
• The wrong top-level key. Most clients use mcpServers. VS Code uses servers. Pasting a config between clients is the usual way this goes wrong.
• Invalid JSON. A trailing comma or a missing quote can make the client skip the file. Run it through a JSON validator, or node -e 'JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"))' path/to/file.json.
• No full restart. Claude Desktop keeps running after you close its window, so quit it from the menu bar or system tray, then reopen it.
• Not approved or not enabled. Claude Code asks before using servers from a project's .mcp.json. Cursor lets you switch servers off. Check that the server is approved and switched on.

"spawn npx ENOENT" or "command not found"

The client can't find the command. Desktop apps don't read your shell profile, so a node or npx installed through nvm, fnm, Volta or asdf may be invisible to them even though it works in your terminal.

• Use an absolute path. Run which npx (macOS and Linux) or where npx (Windows) and put the full path in command.
• Or set PATH for the server. Add an env.PATH that includes the folder with your interpreter. It may replace the inherited PATH, so include the system folders too.
• On native Windows, npx is a batch file that some clients can't start directly. Use "command": "cmd" with "args": ["/c", "npx", "-y", "some-mcp-server"].

"Connection closed" or the server exits immediately

The process started and died before finishing the handshake. The real reason is on the server's stderr, so read the server's log or run the command by hand. Common causes are a missing dependency, a Node or Python version that's too old, a required argument such as an allowed directory that doesn't exist, and a missing API key that makes the server exit on start. With Docker, keep -i and don't use -d: a detached container can't talk over stdio.

Connected, but no tools or auth errors

The server started but can't do its job, which usually means a missing environment variable. Variables set in your shell don't automatically reach a server launched by a desktop app. Put them in the server's env block, or use your client's variable syntax: ${VAR} in Claude Code's .mcp.json, ${env:NAME} in Cursor. Watch for a stray space or line break in a pasted token.

"Unexpected token" or JSON parse errors

On stdio, stdout carries protocol messages and nothing else. If the server prints a banner, a debug line or a Python print, the client tries to parse it as JSON and fails, sometimes only on later messages, which makes the problem look intermittent. If you maintain the server, send all logging to stderr. If you don't, report it to the author. To find the culprit, run the server with stdout redirected to a file and read the file.

Timeouts and slow first starts

The first time npx or uvx runs a package, it downloads it, which can take longer than the client waits. Fixes:

• Warm the cache. Run the command once in a terminal before starting the client.
• Raise the limit. In Claude Code, start with MCP_TIMEOUT=60000 claude, which sets the startup timeout to 60 seconds.

Remote server errors

• 401 or 403: you need to sign in, or your token is wrong. Complete the OAuth flow again. In Claude Code that's /mcp or claude mcp login NAME. Check any Authorization header you set by hand.
• 404: the URL path is wrong. Many servers serve MCP at /mcp, so check the vendor's docs for the exact endpoint.
• 405 from an SSE client: the client is using the old SSE transport against a server that only speaks Streamable HTTP. Set the transport to HTTP, for example "type": "http" in Claude Code and VS Code.
• Works from your laptop but not from a hosted client: connectors in Claude and ChatGPT call your server from the provider's network, so a server on localhost or behind a VPN isn't reachable. It needs a public HTTPS URL.

Too many tools

Every enabled server adds tool definitions to the model's context, and some clients set hard limits. VS Code rejects a request with more than 128 tools, with the error "Cannot have more than 128 tools per request". In any client, a long list of similar tools makes it harder for the model to choose well.

• Disable servers you aren't using, in your client's MCP settings or tool picker.
• Prefer servers with focused tool sets, or ones that let you enable only some toolsets.
• In Claude Code, tool search is on by default, so only tool names load at the start of a session. If a single tool returns too much text, raise MAX_MCP_OUTPUT_TOKENS, which defaults to 25,000 tokens.

Still stuck?

Compare the working Inspector command with your config, line by line: absolute paths, env, the shell and the file location. Then search the server's issue tracker, because the same error has usually been reported before. Every server page on MCPpedia has a generated config for each client, which rules out file and key mistakes, so start from the server's page in the directory.

For real error messages we reproduced, and the reasons behind each, read our in-depth post on MCP servers that fail to start. Client-specific setup is covered in the guides for Claude Code and Cursor.