Claude Code can't connect to an MCP server

Start with the status, not the logs

claude mcp list prints every configured server with a health status, and each status points at a different cause. Reading it first saves guessing:

claude mcp list
claude mcp get <name>

✘ Failed to connect

The server was reached for, and didn't answer properly. For a local (stdio) server, the usual causes are a command that isn't on the PATH Claude Code runs with — common when a tool is installed through a version manager that only activates in interactive shells — and a server that starts and immediately exits because a required environment variable is missing. Run the exact command yourself in a fresh terminal to see its error. On Windows, servers launched with npx need wrapping: claude mcp add --transport stdio my-server -- cmd /c "npx -y some-mcp-server". For a slow-starting server, give it longer with the MCP_TIMEOUT environment variable.

For a remote (HTTP) server, check the URL and transport first. Claude Code retries transient failures such as server errors or refused connections before giving up, but not authentication failures or a wrong address, so a persistent failure is usually a real configuration problem. A JSON entry with a url but no type is skipped entirely with a message asking you to add "type": "http" — the most common hand-editing mistake in .mcp.json.

! Needs authentication

The server uses OAuth and you haven't signed in, or your sign-in expired. Run /mcp in Claude Code, choose the server and sign in, or run claude mcp login <name> from the terminal (--no-browser prints the URL instead of opening one). claude mcp logout <name> clears stored credentials if a sign-in went wrong.

⏸ Pending approval

The server comes from the project's .mcp.json, and you haven't approved it yet. Claude Code asks before using project-scoped servers in an interactive session, because the file could have been written by anyone with access to the repository. Approve it when prompted; if you declined by mistake, claude mcp reset-project-choices brings the prompt back.

⊘ Disabled for this project

Someone toggled the server off in the /mcp panel for this project. Open /mcp and enable it — nothing is wrong with the server itself.

Connected, but a header is empty

One teammate connects to a shared server without trouble; another gets an authentication failure. Check claude mcp list for a missing-variable warning: an unset ${VAR} in .mcp.json is passed through as literal text. And for remote servers, Claude Code deliberately reads certain credential variables — its own API keys, cloud-provider tokens, NPM_TOKEN, HTTPS_PROXY — as empty in url and headers. Rename the server's variable. See MCP scopes in Claude Code.

See how to add an MCP server to Claude Code for the commands, and debugging a stuck Claude Code session when the problem isn't the server.