Claude Code MCP Not Working? Fix Connection and Auth Errors

Jump to: quick triage · "Failed to connect" · server not showing up · stuck on "Needs authentication" · connects but no tools / .mcp.json not working · Figma, GitHub or Playwright server stops mid-session · things worth clarifying

Start Here: Read the Status Before You Touch Anything

1. Run claude mcp list. Claude Code shows a health status next to every configured server: ✔ Connected, ! Needs authentication, or ✘ Failed to connect. A failure status there means that one server couldn't connect, not that the command itself failed.
2. Run claude mcp get <name> on any server that isn't Connected. For a server marked ✘ Failed to connect, this prints the specific cause on its own Issue: line.
3. Decide whether the server is local or remote. A local (stdio) server runs as a command on your machine, often backed by an app like Figma or a browser for Playwright. A remote server connects over HTTP or SSE to a URL. The two fail differently, so the rest of this guide splits on that.

Error 1 - MCP Server Shows "Failed to Connect"

What you see: ✘ Failed to connect next to a server in claude mcp list, and its tools aren't available.

Why it happens

The cause differs by server type. For a local (stdio) server, claude mcp get <name> commonly points to the executable itself: an error like spawn npx ENOENT or "command not found" means Claude Code can't resolve the configured command in the environment it's running in, not that the server's logic is broken. A different failure, -32000: Connection closed during initialize, means the server process started but then exited, wrote invalid output, or rejected the handshake. For a remote (HTTP/SSE) server failing its first connection, Claude Code retries up to three times when the failure is transient — a 5xx response, a connection refused, or a timeout — and marks the server as failed if none of those retries succeed. It doesn't retry an authentication error or a not-found error (401, 403, 404) on that first connection at all, because those require a configuration change to resolve, not a few more seconds of waiting. A different case is a server that connected successfully and then drops mid-session: Claude Code reconnects that one automatically, with exponential backoff, up to five attempts, which is a separate mechanism from the first-connection retries above.

How to fix it

1. Run claude mcp get <name> and read the Issue: line — it names the specific failure instead of just "Failed to connect."
2. If the issue mentions a missing command or ENOENT, replace whatever path is configured with the executable's full path (find it with which <command>, for example which npx) rather than relying on it being on the system's PATH.
3. If the server's process exits immediately, run the exact command configured for it directly in a terminal — that surfaces the real startup error instead of Claude Code's generic failure status.
4. If it's a remote server returning 401/403, go to Error 3 to re-authenticate. If it's returning 404, fix the registered URL. If it's a 5xx, connection-refused, or timeout failure, it should clear within the automatic retry window; to force an immediate retry instead of waiting, run /mcp reconnect all.

What you should see: claude mcp list shows ✔ Connected for the server, and claude mcp get <name> no longer prints an Issue: line.

Error 2 - A Server Doesn't Show Up Where You Expect

What you see: a server you configured is missing from /mcp, missing from claude mcp list, or Claude Code reports no servers at all.

Why it happens

Claude Code stores MCP servers in one of three scopes: local (the default, stored in ~/.claude.json, not shared with anyone else), project (stored in .mcp.json in the project root, shared through version control), and user (also in ~/.claude.json, but following you across every project). A server added in one scope only shows up in a session that reads that scope — most often, a server added while working in one project directory simply isn't visible from a different one. Separately, a server can be missing because the config entry itself is malformed: a syntax error anywhere in .mcp.json can stop the whole file from loading, not just the one broken entry.

How to fix it

1. Check which scope the server should live in. If it needs to be available to anyone who opens this project, re-add it with --scope project so it lands in the project's own .mcp.json: claude mcp add --transport http <name> --scope project <url>. If it should follow you personally across projects, use --scope user instead.
2. Validate .mcp.json's syntax directly — a single misplaced comma or bracket is enough to stop the file from loading.
3. Start a fresh Claude Code session after editing the config, and run claude mcp list again to confirm the server now appears with a status.

What you should see: the server appears in both claude mcp list and /mcp, with a status rather than being absent.

Error 3 - Stuck on "Needs Authentication"

What you see: claude mcp list shows ! Needs authentication next to a remote server, and none of its tools are available.

Why it happens

Some remote servers require an OAuth 2.0 sign-in before Claude Code can use them. That sign-in doesn't happen automatically in the background — Claude Code surfaces the status and waits for you to complete it through the /mcp command.

How to fix it

1. Run /mcp inside your Claude Code session and select the server showing Needs authentication.
2. Complete the sign-in flow it opens. This is a one-time step per server per scope.
3. If the status doesn't update afterward, run /mcp reconnect all to force an immediate recheck — Claude Code's automatic retry schedule is built for transient connection drops, not for an auth status that's waiting on you.

What you should see: the server flips to ✔ Connected in claude mcp list, and its tools appear under /mcp.

Error 4 - Server Connects but Has No Tools, or .mcp.json Changes Don't Take Effect

What you see: claude mcp list shows ✔ Connected, but no tools from that server appear anywhere, or an edit you made to .mcp.json doesn't seem to have changed anything.

Why it happens

A server that connects but exposes zero tools usually failed a step after the connection itself, most often because an environment variable or API key it needs at startup is missing. A config edit that seems to do nothing is usually one of two things: the running session hasn't picked up the change yet, because Claude Code reads .mcp.json when a session starts, or the edited JSON is invalid and silently failed to load.

How to fix it

1. Check that every environment variable or secret the server's entry references is actually set in the environment Claude Code is running in, not just in a file you assume it reads from.
2. Re-validate .mcp.json's syntax after any edit.
3. Start a new Claude Code session to force the config to reload, rather than assuming an open session will pick up the change.
4. Run claude mcp get <name> to confirm which scope and which file Claude Code actually loaded the server from — this catches the case where an edit landed in the wrong file.

What you should see: the server's tools appear under /mcp, and a change to .mcp.json is reflected the next time you check claude mcp list after a new session.

Error 5 - A Figma, GitHub or Playwright MCP Server Stops Working Mid-Session

What you see: a server backed by a local app or process — Figma's, GitHub's or Playwright's MCP integrations are commonly set up this way — worked earlier in the session and then starts failing tool calls, or flips to ✘ Failed to connect without you changing anything.

Why it happens

These are typically stdio servers: Claude Code talks to them over the server's standard input and output, and that connection depends on the underlying app or process staying open. If that app closes — the Figma desktop app, the local process backing a GitHub MCP server, a Playwright browser instance — the stdio server doesn't reconnect by itself the way a remote HTTP server does. Separately, if the server writes its own log output to stdout instead of stderr, that text corrupts the JSON-RPC protocol stream Claude Code uses to talk to it — the messages they exchange to request and return tool results — and can look like a random, unexplained failure partway through a session.

How to fix it

1. Confirm the underlying app or process is still running. A closed app is the most common cause for this specific pattern.
2. Restart that app or process, then run /mcp reconnect all rather than waiting — Claude Code's automatic backoff reconnection is built for remote servers, not for a local process that has to be restarted by you.
3. If it still fails after that, run claude mcp get <name> for the exact Issue: line. If you maintain the server yourself, check whether it logs to stdout instead of stderr.

What you should see: claude mcp list shows the server as ✔ Connected again, and its tools respond normally.

Things Worth Clarifying

• A dropped connection retrying for a few seconds isn't a bug. Claude Code automatically retries a dropped remote server with exponential backoff, up to five attempts, before it shows as failed. Seeing a brief reconnect isn't itself a problem to fix.
• MCP_TIMEOUT and a tool's own timeout are two different settings. MCP_TIMEOUT controls how long Claude Code waits for a server to start up (for example, MCP_TIMEOUT=10000 claude for 10 seconds). A slow individual tool call is controlled separately, by adding "timeout": 600000 to that server's entry in .mcp.json. Raising one doesn't change the other.
• "Needs authentication" isn't the same failure class as "Failed to connect." The first means Claude Code is waiting on you to sign in through /mcp; the second means the connection itself didn't succeed. Treating both the same way wastes time on the wrong fix.

When It Isn't a Bug

• An idle connection closing isn't a bug. Claude Code closes an idle connection after 5 minutes by default for HTTP, SSE, WebSocket and claude.ai connector servers, and after 30 minutes for stdio servers. Reconnecting after a long gap is expected, not a failure.
• A remote server not auto-retrying on an authentication or not-found error isn't a bug. On a first connection, Claude Code only auto-retries the transient class of failures (5xx, timeouts, connection refused). A 401, 403 or 404 points to something that needs an actual fix — authentication or the URL — so it's left for you to resolve rather than retried blindly.
• A local server failing when its app is closed isn't a Claude Code bug. A stdio server depends on the process behind it; closing that process (quitting Figma, closing the browser Playwright was driving) is expected to break the connection until it's reopened.

What to Include When You Ask for Help

• the exact status claude mcp list shows for the server (Connected, Needs authentication, or Failed to connect);
• the Issue: line from claude mcp get <name>;
• whether the server is local (stdio) or remote (HTTP/SSE), and the HTTP status code if a remote one returned one;
• which scope it was added with (local, project or user) and whether it lives in .mcp.json or ~/.claude.json.

Related

For other Claude Code problems unrelated to MCP — reverted changes, context compaction mid-feature, permission denials and more — see the full Claude Code troubleshooting guide. For an overview of what Claude Code covers as a platform, see the Claude Code platform page.

Frequently Asked Questions

Sources

Checked on October 9, 2026:

• Claude Code docs: Connect Claude Code to tools via MCP
• Aident.ai: How to Fix Claude Code MCP Failed to Connect Errors
• Wmedia: MCP "Failed to connect" in Claude Code
• Hustle to AI: Claude Code MCP Server Not Working? 8 Fixes That Actually Work