Claude Code MCP Failed to Connect: How to Fix It (Claude Code)

✘ Failed to connect means Claude Code found your MCP server's configuration but could not start it or reach it. The fastest fix is to run claude mcp get <name> and read the Issue: line, which carries the HTTP status or error code. Fix that one thing, then select Reconnect for the server in /mcp.

Checked against: Anthropic's Claude Code MCP documentation, the Debug your configuration page and the Claude Code error reference on 2 November 2026. eSEOspace did not run these steps on your machine; follow Anthropic's pages if they differ.

What this error means

Anthropic's docs say a failure status "means Claude Code couldn't connect to that server, not that the list command failed." The detail Claude Code adds is "the HTTP status or error code, plus any error text the server returned." Credential-like text is redacted from it.

There is a related status with no detail. ✘ Connection error hides the exception text because it can contain the server URL, which may include secrets. For that one, use the debug log below.

Claude Code retries transient problems on its own. For HTTP and SSE servers, the docs say a first connection that fails with a 5xx, a refused connection or a timeout is retried up to three times before the server is marked failed. Authentication and not-found errors are not retried, because they need a configuration change.

Quick fix

1. Run claude mcp get <name> and read the Issue: line.
2. If it shows 401 or 403, fix the token or header, or remove the Authorization header and sign in with claude mcp login <name>.
3. If it is a local (stdio) server, run its command by hand in a terminal to see whether it starts.
4. Replace any relative path in command or args with an absolute path.
5. If the server is slow to start, launch with a longer startup timeout, for example MCP_TIMEOUT=10000 claude for 10 seconds.
6. In the session, open /mcp, select the server, and choose Reconnect. On v2.1.284 or later you can run /mcp reconnect all.

Fix by client / OS

Claude Code: stdio server exits on start

Most local failures come from the launch command. The debug page says relative file paths are a frequent cause. It recommends absolute paths for local scripts, while executables on your PATH such as npx or uvx work as is.

Check the -- separator too. In claude mcp add, everything after -- goes to the server untouched. Without it, Claude Code tries to parse the server's own flags as its options:

claude mcp add --transport stdio --env API_KEY=YOUR_KEY myserver -- npx -y some-mcp-server --port 8080

That format was checked against Anthropic's docs on 2 November 2026. The docs add that --env can't sit directly before the server name, so keep another option such as --transport stdio in between. If npx or uvx itself is missing, see our guides to spawn npx ENOENT and uvx not found.

Claude Code: remote server returns 401 or 403

For a server whose Authorization header you set yourself, Anthropic says a 401 or 403 "doesn't flag the server" for sign-in. Claude Code reports a failed connection instead, because the credential to fix is the one you configured.

Three common causes:

• A placeholder token. The docs note that claude mcp add accepts a placeholder value, and the server fails later.
• Hidden whitespace. A pasted token with a trailing newline triggers a warning like Leading or trailing whitespace in: headers.Authorization. Claude Code does not trim it, so edit the value.
• A credential variable read as empty. In a remote server's url and headers, Claude Code reads some credential variables as empty. Writing Bearer ${ANTHROPIC_AUTH_TOKEN} sends Bearer with nothing after it. Run claude --debug-file /tmp/claude-debug.log and search for never expanded toward a remote server.

If the server supports OAuth, remove the header and run claude mcp login <name>. Our 401 Unauthorized guide covers the server side.

Claude Code: missing or empty environment variables

If a ${VAR} in the config is unset with no default, Claude Code warns and keeps the literal ${VAR} text. If the variable is set to an empty string, a URL can collapse to /mcp, and claude mcp list reports 'url' is not a valid URL. Set the variable, or unset it so a ${VAR:-default} fallback applies.

Claude Code on Windows

Anthropic documents one Windows-specific behavior: on shutdown, Claude Code closes the server's stdin and ends its process tree if it is still running 300 milliseconds later. If your server needs longer to clean up, handle stdin closing promptly. For start-up failures specific to Windows, see MCP server failed to start on Windows.

Where to find the logs

• claude mcp list shows the failure detail inline. claude mcp get <name> shows it on the Issue: line, and the /mcp detail view has the same text.
• claude --debug=mcp writes MCP output, including the server's stderr, to ~/.claude/debug/<session-id>.txt, per the debug page.
• claude --debug-file <path> writes the debug log to a file you choose.

If it still fails

Test the server outside Claude Code. The MCP Inspector connects to the same command or URL and shows the raw JSON-RPC traffic. If it works there but not in Claude Code, compare the environment, the working folder and the headers. Our guide to servers that work in Inspector but not Claude walks through that comparison.

If a remote server drops mid-session rather than at start, Anthropic says Claude Code retries up to five times in an interactive session and then shows MCP server "<name>" disconnected · open /mcp to reconnect. Look up any JSON-RPC code you see with our MCP error code lookup.

Next step

If a server you built fails in Claude Code but nowhere else, the cause is often in its startup or auth flow. eSEOspace's MCP development team can review the server and its configuration with you.

Frequently asked questions