Error messages

✘ Failed to connect

✘ Failed to connect

An MCP server is a separate program or web service that hands Claude Code extra tools. When Claude Code can't get a working connection to one, claude mcp list puts this next to its name:

✘ Failed to connect

Older builds said it differently, with a red 1 MCP server failed counter in the status bar. That wording is what most people search for (572 issues in the anthropics/claude-code repo quote "MCP server failed" as of September 25, 2026), but I couldn't find it anywhere in version 2.1.282. The server behind it is just as broken either way, and the fix is the same.

Where to find the actual reason

The status line on its own tells you almost nothing. Since v2.1.219, Anthropic's MCP documentation says, claude mcp list appends the failure detail to that line, and claude mcp get <name> prints it on an Issue: line: an HTTP status or error code plus whatever text the server sent back. The server's page inside /mcp has the same Issue: row.

If you see ✘ Connection error instead, you get no detail at all. The docs explain why: the exception text there can contain the server's URL, and URLs often carry secrets, so Claude Code leaves it out. For that case, and for local servers that die quietly, the debug log is the better source. Start a session with claude --debug-file /tmp/claude-debug.log, open /mcp, then search the file for your server's name.

The 30-second startup deadline

This part surprised me. In the 2.1.282 code, every connection attempt races a timer, and the timer comes from one small function: it reads MCP_TIMEOUT and, if that isn't set, uses 30000 milliseconds. When the timer wins, the debug log gets this:

MCP server "sqlcl" connection timed out after 30000ms

That exact line is from a July 2026 report on version 2.1.220, where an Oracle SQLcl server on Windows failed every time even though the same command came up in about 11 seconds under MCP Inspector (a debugging tool for MCP servers). Servers that download something or warm up a runtime before answering can blow straight through 30 seconds on a cold start.

The fix the docs give is an environment variable read at launch:

MCP_TIMEOUT=90000 claude

It's in milliseconds. There's a second setting with a similar name, MCP_CONNECT_TIMEOUT_MS (default 5000), and it does something else: it's how long startup blocks waiting for servers before carrying on, and a server still connecting at that point keeps going in the background. Raising it won't rescue a server that times out.

One caution. A January 2026 report that's still open found that values above 60 seconds weren't honored: the log said it was starting with a 100000ms timeout, then failed at 60 seconds with MCP error -32001: Request timed out. The 2.1.282 code now passes the same MCP_TIMEOUT value into the connect call, which looks like it should cover that case, but I haven't tested it, so don't take that as settled.

When a working server drops mid-session

A server that was connected and then lost its connection gets retried in the background. According to the docs, after five failed attempts Claude Code marks it failed and shows MCP server "<name>" disconnected · open /mcp to reconnect. For HTTP and SSE servers the very first connection gets up to three retries on errors that look temporary, like a 5xx response or a refused connection. A 401 or 403 from a server whose Authorization header you set yourself is reported as a failed connection too, and no amount of retrying will fix it: that token needs replacing.

A tool call to a server in this state fails with MCP server "<name>" is not connected. Picking Reconnect in /mcp reruns the whole connection, and a failure there comes back as Failed to reconnect to <name> followed by whatever reason Claude Code has.

A stale counter isn't always a dead server

On older versions the red counter could lie. In a March 2026 report on 2.1.88, /mcp said the server had reconnected and its tools worked, yet 1 MCP server failed stayed in the status bar for the rest of the session. So check /mcp before you start pulling your configuration apart. If the server shows connected there, the warning was out of date.