Why is my MCP server disconnected?

claude mcp get <name>

Shows the HTTP status or error code behind the failure.

Answer

Start with claude mcp get <name>. It shows the HTTP status or error text behind the failure. For an HTTP server, curl -I <url> tells you the rest: a 404 or 405 means the server is up, a 401 or 403 means you need to authenticate, no response means the URL or your network. For a stdio server, run its command directly to see the real error.

What it does

Two statuses mean the server did not answer, and they start you in different places. Find the one you saw.

✘ Failed to connect

Carries a failure detail: the HTTP status or error code and any text the server returned, which often names the problem outright, a missing header, a rejected token. claude mcp list appends it to the status line; claude mcp get <name> and the server's view in /mcp show it on an Issue: line. Credential-like text is redacted and the expanded URL never appears.

Before v2.1.219 this status showed nothing but itself. If the detail is missing, check your version with claude --version before assuming the server said nothing.

✘ Connection error

Appends no detail on any version, because the exception text could embed the server URL and its secrets. Go straight to the manual checks below.

! Needs authentication

A different case, and not a failure: the server wants a token you never configured. Add one rather than debugging the connection.

Note that the first two statuses can *also* mean authentication. An HTTP server that rejects the token in headers.Authorization reports a connection failure, not this. So a rejected token looks like a connection problem, while a missing one does not.

For an HTTP server, check reachability yourself:

curl -I https://mcp.sentry.dev/mcp

In PowerShell write curl.exe. Plain curl is an alias for Invoke-WebRequest, which has no -I.

The response classifies the problem:

404 or 405 — the server is up. Many MCP endpoints answer only POST, so this still confirms the URL is reachable.
401 or 403 — the server is up and wants authentication.
no response — check the URL and your network.

For a stdio server, run the configured command directly:

npx -y @playwright/mcp@latest

If it starts and waits for input, the server works. Compare what claude mcp get <name> stored against what you just typed. If it errors, the message names what is missing.

When to use it

Work in that order. The detail on the status is free and often sufficient; the curl check costs one command and eliminates half the possibilities.

For an HTTP server the status is already the result of retries: three at startup on a transient error such as a 5xx or a timeout, five with backoff if the connection drops mid-session. A stdio server gets no automatic retry; reconnect it from /mcp.

Also read the warnings in claude mcp list. Claude Code flags config values with hidden leading or trailing whitespace, a common cause of authentication failures right after pasting a token.

Example

A 404 from an HTTP server has its own message in /mcp:

MCP endpoint not found at https://mcp.example.com. Check the URL in your MCP config.

The message names the origin without the path, so check the full URL:

claude mcp get <name>

Then fix it by re-adding:

claude mcp remove <name>
claude mcp add --transport http <name> <correct-url>

A slow first start is not a failure. The default startup timeout is 30 seconds, and a stdio server's first run can exceed it while npx downloads:

MCP_TIMEOUT=60000 claude

If .mcp.json edits seem to do nothing, restart the session, because the file is read at startup. Quit and run claude again rather than clearing the context, which is a different operation: it empties what Claude can see, not what Claude Code has loaded from disk.

If servers still do not appear, run claude mcp list and look for a parse warning: malformed entries are skipped and the offending field is named. If you declined the approval prompt earlier:

claude mcp reset-project-choices

Common mistakes

Treating the first Failed to connect as final. For a newly added stdio server, wait for the package download and check again.

Skipping claude mcp get. It is where the HTTP status and error text live. The list view only shows the symptom.

Reading a 404 from curl as broken. It means reachable. MCP endpoints commonly reject HEAD and GET.

Forgetting whitespace in a pasted token. It survives the paste, breaks the auth, and looks like a server problem.