Claude Code MCP server failed to connect: how to fix it

When Claude Code says an MCP server failed to connect, the server either never started or started and never completed the MCP handshake. Run claude mcp get <name> first: it prints an Issue: line with the error the server gave. Common causes are a relative path, a missing variable, bare npx on native Windows and a rejected credential. A server that never shows up at all is a different problem, usually a .mcp.json in the wrong place.

What follows comes from Anthropic's Debug your configuration and MCP pages, both read on 24 October 2026, when the newest version in Anthropic's changelog was v2.1.310.

What "Failed to connect" means in claude mcp list#

claude mcp list checks each server and prints one of three health states: ✔ Connected, ! Needs authentication or ✘ Failed to connect. A failure is about that server, not the list command. Three other states never come from a connection attempt, because they record a decision: ⏸ Pending approval (a .mcp.json server you haven't approved), ⊘ Disabled for this project (turned off for the project; /mcp turns it back on) and ✘ Rejected, which only claude mcp get shows (a disabledMcpjsonServers entry blocks it).

Since v2.1.219, a failed server's line carries the detail: the HTTP status or error code, plus any text the server sent back. claude mcp get <name> puts the same text on an Issue: line, and the server's page in /mcp shows it too. That one line usually names the cause.

How it retries depends on the transport. A remote HTTP or SSE server whose first connection fails with a 5xx, a refused connection or a timeout is retried up to three times. A stdio server, the kind started with a command such as npx or uvx, is not retried in an interactive session: it stays failed until you choose Reconnect in /mcp. How Claude Code reconnects a server that drops mid-session, and how to give a slow server longer to start, is in the MCP timeout guide.

Claude Code MCP server failed to connect: causes and fixes#

A 401 on a server whose Authorization header you set yourself shows as a failure, not as "needs authentication", because the credential to fix is the one in your config. And a ${VAR} in the config that nothing sets gets a warning in claude mcp list and /mcp naming the variable, while the server still loads with the text ${VAR} left in.

Find the real error#

1. Run claude mcp get <name> and read the Issue: line.
2. For a stdio server, copy its command and args and run them yourself in a terminal, in the same folder. A missing package, a wrong Node version or a crash on start shows up right there.
3. Start claude --debug=mcp, reproduce the failure and open ~/.claude/debug/<session-id>.txt. The server's stderr lands there.
4. Fix the cause, then choose Reconnect in /mcp. From v2.1.284, /mcp reconnect all retries every server that failed or needs a sign-in.

A stdio server can also fail because it prints its own messages to stdout. The MCP specification says a stdio server must not write anything to stdout that is not an MCP message; logs belong on stderr. A banner or a console.log there breaks the stream Claude Code reads.

If nothing stands out, claude --safe-mode starts a session with MCP servers, hooks, skills and CLAUDE.md all switched off. If the problem goes away, it lives in your own configuration.

Why is .mcp.json not loading?#

Claude Code reads project servers from one place: .mcp.json at the root of the repository. Each server sits under mcpServers, with its command, its arguments and any variables it needs:

{
  "mcpServers": {
    "docs": {
      "command": "node",
      "args": ["/Users/you/tools/docs-server/index.js"],
      "env": { "DOCS_TOKEN": "${DOCS_TOKEN}" }
    }
  }
}

Servers you add with claude mcp add don't go in that file at all: local and user scope live in ~/.claude.json. That's a different file from ~/.claude/settings.json, which holds settings, permissions and hooks but no servers. Setting up MCP servers for every project walks through the three scopes and which one wins when a name appears twice.

A cloned repository can't approve its own servers. enableAllProjectMcpServers committed in the project's .claude/settings.json is ignored in a folder you haven't trusted, and the server stays at ⏸ Pending approval. Run claude in the folder and accept the trust dialog first.

npx MCP servers on native Windows#

Older Claude Code versions warned that Windows needs a cmd /c wrapper to run npx. Version 2.1.119 (23 April 2026) removed that warning as a false positive, and the current MCP page doesn't mention a wrapper. Bug reports filed later on native Windows still show bare npx servers at Failed to connect, with spawn npx ENOENT or EINVAL. The reporters trace it to npx being a npx.cmd file, which Node refuses to start without a shell (issue 58510, issue 68221). Both were closed without a fix named in the changelog.

The workaround those reports give is to start cmd and pass npx as an argument:

{
  "mcpServers": {
    "context7": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@upstash/context7-mcp"]
    }
  }
}

Write it into .mcp.json by hand: a January 2026 report (issue 20061) found claude mcp add saving /c as C:/. Under WSL none of this applies: Claude Code runs as a Linux program there (Windows or WSL compares the two). Codex reads its servers from a different file and fails in its own ways; that is in Codex MCP server failed to start.

How Shuriken does it#

Shuriken keeps one list of MCP servers instead of a config per folder and per computer. In Global MCPs you add a server once, pick the projects it belongs to, and sign in to it once. Every chat in those projects is handed the server when it starts, in Claude Code, Codex or another agent, on any of your accounts, and the sign-in follows you, sealed, to your other computers. The sign-in belongs to the server, so switching accounts doesn't ask for it again. The list reaches chats you run in Shuriken; a claude you start in a terminal still reads its own config files, as it would without Shuriken.

The list also says, per server, whether it can run on the project's computer: Ready, Not starting with the error the server gave, Needs sign-in, Waiting for approval, Missing on that device when npx or another command isn't installed (with an Install button for the ones Shuriken knows how to install, such as Node and uv), or Needs a secret when a ${VAR} in its config is set nowhere on that device. Those readings come from the same claude mcp list health check and a test start of the server, never from a model call. If you want to try it, download Shuriken.