When a Claude Code MCP server fails to connect or never appears, work through the configuration points the docs name. Run /mcp, then check that .mcp.json sits at the repository root with servers under mcpServers, that remote entries have a type, that local paths are absolute and that you approved the project server.
When a Claude Code MCP server shows as failed or never appears, run /mcp to see each server's status, then check these five configuration points in order: the file is .mcp.json at the repository root, the servers sit under mcpServers, remote entries carry a type, local paths are absolute, and you approved the project server. Compared with the MCP documentation and the debug your configuration page as read on 14 November 2026. The steps are taken from those pages, not run against a live server.
How to tell an outage from a local problem
A server that worked yesterday and fails everywhere today may be down on the vendor's side. Check the vendor's own status page first. If Claude itself is slow or erroring, check status.claude.com and the Claude Code status hub. A server that has never connected, or fails only in one project, is more likely a local configuration problem, which is what the rest of this guide covers.
What does /mcp tell you first?
Inside a session, /mcp shows your servers and their connection status. From a shell, claude mcp list shows servers with health status and claude mcp get <name> shows one entry. If a server is not listed there, Claude Code did not load it from the file you edited.
claude mcp list
claude mcp get docs
claude --debug=mcp
The debug your configuration page recommends claude --debug=mcp when a server connects but lists zero tools, and says to read the server's stderr in the debug log at ~/.claude/debug/<session-id>.txt. The docs do not list what else that log holds, so treat it as private and check it before you share any of it.
Symptom, likely cause and fix
| Symptom | Likely cause | What to do |
|---|---|---|
Server never appears in /mcp | File is inside .claude/, or servers sit under a top-level servers key (VS Code's format) | Put .mcp.json at the repository root and use the mcpServers key |
Servers added under mcpServers in settings.json never load | settings.json does not read that key | Define them in .mcp.json, or run claude mcp add --scope user |
| Remote server skipped | Entry has a url but no type, so it is read as stdio | Add "type": "http" (or sse, ws) |
| Server listed but disabled | One-time project approval prompt was dismissed | Run claude mcp reset-project-choices, restart Claude Code and approve the server |
| Fails from some directories only | Relative path in command or args resolves against the launch directory | Use an absolute path for local scripts |
| Connected with zero tools | Server started but returned no tool list | Choose Reconnect in /mcp, then run claude --debug=mcp |
| Authentication fails on a remote server | A credential variable such as ANTHROPIC_API_KEY inside url or headers reads as empty | Copy the value into a variable with your own name and reference that |
Each row follows the debug your configuration and MCP pages. The sections below expand on several of them.
What should .mcp.json look like?
Project-scoped servers live in .mcp.json at the project root, under mcpServers. The documented transport types are http (alias streamable-http), sse, ws and stdio. SSE is deprecated, so prefer http where the server supports it. A working pair of entries:
{
"mcpServers": {
"docs": {
"type": "http",
"url": "https://example.com/mcp"
},
"local-tool": {
"type": "stdio",
"command": "npx",
"args": ["-y", "some-mcp-server"]
}
}
}
Executables on your PATH such as npx and uvx work as written. The docs say an entry with a url but no type is not accepted, and Claude Code reports a message saying so. The names above are placeholders, so substitute your own server.
Why is an environment variable not reaching the server?
Claude Code expands ${VAR} and ${VAR:-default} in command, args, env, url and headers. An unset variable with no default loads as the literal text ${VAR} and claude mcp list reports a warning. An empty string counts as set, so a default will not replace it. In a remote server's url and headers, credential variables such as ANTHROPIC_API_KEY read as empty on purpose, even when set, so the server receives no credential. For a stdio server, the docs recommend per-server env inside the entry, because it does not depend on the launch environment or workspace trust.
Which scope and approval apply?
Three scopes exist. Local is the default and is stored in ~/.claude.json for the current project only. Project lives in .mcp.json and is shared through version control. User applies to all your projects and is also stored in ~/.claude.json. When one server name is defined in several places, Claude Code uses the highest-precedence entry and does not merge fields. Project servers need your approval in an interactive session. claude mcp reset-project-choices resets earlier approval choices. In claude -p runs, Claude Code cannot show the prompt and loads project servers without asking.
What happens after a connection drops?
Per the docs, a remote server that drops mid-session is retried up to five times with exponential backoff, starting at one second and doubling each time, then shows as failed with a notification telling you to open /mcp to reconnect. An HTTP or SSE server's first connection is retried up to three times after a transient error. A stdio server that fails on its first connection needs Reconnect from /mcp. Startup time can be raised with MCP_TIMEOUT, for example MCP_TIMEOUT=10000 claude. A per-server timeout in milliseconds overrides MCP_TOOL_TIMEOUT for that server.
Two open GitHub issues describe HTTP servers that stayed failed: issue 108930 (a server that was not yet listening when the session started, fixed only by Reconnect from /mcp) and issue 105752 (an Agent SDK session that never reconnected after a restart, where the docs promise background retries for about half an hour). Both were open on 14 November 2026. Anthropic has not confirmed either, so treat them as user reports.
How do you rule out everything else?
Start claude --safe-mode. The docs say it disables CLAUDE.md, skills, plugins, hooks, MCP servers and other customizations for the session, while authentication, model selection, built-in tools and permissions work normally. If a hang or error disappears, one of those was the cause. Servers are not the only thing that can look like a failure: a bad hook can too, as covered in Claude Code hooks not firing. If an instruction file seems to be ignored rather than a server missing, your CLAUDE.md is not a control explains why.
Do not paste your .mcp.json with real tokens, your debug log or ~/.claude.json into a chat, issue or website. Copy your config somewhere safe before editing it, and never delete it as a first step.
More practical writing for people building with AI tools is on the Lead Source blog.
Fixed? Two optional things
Check Anthropic’s status and get an alert when an incident is resolved: Claude Code status and alerts, an independent resource by Lead Source.
Official source: status.claude.com.
Written by the team at Lead Source, where the day job is lead source tracking: working out which marketing actually brings customers.