Claude Code MCP Not Connecting: Fixes That Work

Claude Code MCP not connecting: causes and fixes

When an MCP server will not connect in Claude Code, work through these six causes in order. Each links to the full fix below.

1. Wrong config scope. The server was added to a scope this session does not read. Run claude mcp list; re-add it at the scope you want (--scope project or --scope user).
2. Command or package not installed / not on PATH. The launch command never starts. Run the exact command in a plain terminal; install the package or use an absolute path to the binary.
3. Missing or wrong environment variable. The server starts but tool calls fail with auth errors. Declare every required variable explicitly in the server's env block, then restart.
4. Stale config from an open session. You edited .mcp.json while a session was running. Restart Claude Code so it re-reads the config at start.
5. An unapproved project .mcp.json. Committed project servers need approval before they run. Approve them when prompted (after checking what they launch).
6. A crashing or slow-to-start server. Read the logs with claude --debug to see the real error (a handshake timeout or a stack trace), then fix that specific cause.

The rest of this page walks each cause in detail, shows how to read the logs, and ends with the config discipline that stops it recurring.

The symptom

You added an MCP server to Claude Code, but its tools never show up. Depending on what is wrong, you see one of a few things: the server is listed as failed when you run claude mcp list, the tools simply do not appear in the session, Claude says it has no tool for a task you know the server provides, or the server shows as connecting and then drops. Sometimes there is no error at all, the server is just silently absent.

MCP (the Model Context Protocol) connects Claude Code to external systems: databases, browsers, issue trackers, internal APIs. The ecosystem is large, community directories now index well over ten thousand servers, as our State of Claude Code 2026 report documents, so connection issues are common simply because most setups run several servers at once. When a server will not connect, the cause is almost always one of six things, and each has a precise fix. This page walks them in rough order of likelihood, shows you how to read the logs that tell you which one you have hit, and ends with the configuration habits that stop it recurring.

If you are setting up MCP for the first time rather than debugging a broken setup, start with Claude Code MCP setup and the Claude Code MCP servers overview, then come back here when something does not connect.

Cause 1: the server is in the wrong config scope

This is the single most common reason, and the most confusing, because nothing is technically broken. Claude Code reads MCP servers from more than one place: a project-level .mcp.json (shared with the project), a project-local user config, and a global user config. A server added to one scope is invisible from a session that reads a different scope.

The classic version: you ran claude mcp add in one directory, then opened Claude Code in another directory, and the server is "missing." Or you added it to your global config and expected it in a project that only loads project-scoped servers. The server exists; the session just is not looking where you put it.

The fix. Confirm what scope the session actually sees:

claude mcp list

If your server is absent, you added it to a scope this session does not read. Re-add it at the scope you want. To add a project-shared server that lives in the repo's .mcp.json:

claude mcp add --scope project my-server -- npx -y @some/mcp-server

To add it just for yourself across all projects, use the user scope:

claude mcp add --scope user my-server -- npx -y @some/mcp-server

Decide deliberately: a server the whole team needs belongs in project scope (committed .mcp.json); a personal server belongs in user scope. Most "server not found" reports are this and nothing more.

Cause 2: the command or package is not installed or not on PATH

An MCP server is launched by a command, often npx, node, python, uvx, or a path to a binary. If that command is not on the PATH that Claude Code launches with, or the package is not installed, the server process never starts.

The tell is a server that shows as failed immediately, with a log line about a command not found or a module that cannot be resolved. npx -y @some/server failing usually means the package name is wrong or the registry fetch failed; python -m some_server failing usually means the package is not installed in the environment Claude Code is using.

The fix. Run the exact launch command yourself, in a plain terminal, and watch it start:

# Whatever your config has as the command + args, run it directly:
npx -y @some/mcp-server
# or
python -m some_mcp_server

If it errors there, it will error for Claude Code too. Install the missing package, correct the package name, or use an absolute path to the binary in your config so PATH differences cannot bite:

claude mcp add my-server -- /usr/local/bin/node /abs/path/to/server.js

Using an absolute path for the command is the most reliable fix when the same config works in one shell but not another, because it removes the PATH variable from the equation entirely.

Cause 3: a missing or wrong environment variable

Most useful MCP servers need credentials: an API key, a database URL, an auth token. If the server expects an environment variable that is not set, or is set to the wrong value, it either exits on startup or connects and then fails every tool call with an auth error.

The tell is a server that starts but whose tools all fail, or a log line about a missing variable, a 401, or an undefined token. This is different from causes 1 and 2: the process is running, it just cannot authenticate.

The fix. MCP server env vars are declared in the server's config entry, not inherited blindly from your shell. In .mcp.json the entry carries an env block:

{
  "mcpServers": {
    "my-db": {
      "command": "npx",
      "args": ["-y", "@some/db-mcp-server"],
      "env": {
        "DATABASE_URL": "postgresql://...",
        "API_KEY": "your-key-here"
      }
    }
  }
}

Confirm every variable the server documents is present in that env block and has a real value. Do not assume the server picks up a variable that happens to be exported in your shell; declare it explicitly in the config. If you would rather not commit a secret, reference it from an environment file your launcher loads, but make sure the value reaches the server process. After fixing, restart the session so the new config is read.

Cause 4: stale config from a previous session

Claude Code reads MCP configuration at session start. If you edit .mcp.json or run claude mcp add while a session is already open, the running session does not see the change. People then conclude the server "does not work" when it would connect fine in a fresh session.

The tell is the most frustrating one: the config looks correct, claude mcp list may even show the server, but the current session still has no tools from it. Nothing is wrong with the config; the session is just running on the old view.

The fix. Restart Claude Code so it re-reads configuration:

# Exit the current session, then start a fresh one in the same directory
claude

After restart, verify the server is connected:

claude mcp list

A connected server appears with its tools available. As a rule, treat MCP config as read-at-start: change it, then restart. This one habit eliminates a large fraction of "it is not connecting" confusion that is really "the session predates the change."

Cause 5: a project .mcp.json you have not approved

For safety, Claude Code does not silently run arbitrary MCP servers from a project's committed .mcp.json the first time it sees them. A project-scoped server can launch a process on your machine, so the tool asks for approval before trusting servers defined in a repository you opened. Until you approve, those servers do not connect, which reads as "not connecting" even though the mechanism is working as intended.

The tell is a server defined in the repo's .mcp.json that never appears, especially right after you cloned or pulled a project, with no obvious error, because this is a trust gate rather than a failure.

The fix. Approve the project's MCP servers when prompted, or check the project MCP status and approve from there:

claude mcp list

If a project server is pending approval, accept it (only after you have looked at what .mcp.json actually launches, the same caution you would apply to any code from a repo). Once approved, the server connects on the next session. If you reset MCP approvals or move the project, you may be prompted again, which is the gate doing its job.

Cause 6: a crashing or slow-to-start server (read the logs)

If none of the above fit, the server process itself is failing: it throws on startup, times out before it is ready, or crashes mid-session. At this point you stop guessing and read the logs, which name the actual failure.

The fix. Get verbose output and inspect the MCP logs. Launch Claude Code with debug output to see connection attempts and errors inline:

claude --debug

That surfaces the server's stdout/stderr and the connection handshake, so a stack trace, a port conflict, or a timeout shows up directly. The logs answer questions guesswork cannot: which step failed, what the server printed before dying, whether it ever completed the MCP handshake. For a server you wrote or are extending, this is also where you confirm it speaks MCP correctly rather than just running.

Two specific failure shapes to watch for in the logs:

• Handshake timeout. The process starts but never completes the MCP initialisation in time, often because it does heavy work (a large index load, a slow network call) before signalling ready. Fix the server to become ready faster or defer the heavy work until after it has connected.
• Immediate crash with a stack trace. A real bug in the server or a bad argument. The trace tells you where; fix the input or the server.

Once the logs name the cause, the fix is usually small and specific. The mistake is trying random config changes before reading them.

Prevention: a CLAUDE.md and config discipline

Most recurrences come from the same few habits. Encode the discipline so it stops happening.

Add an MCP section to your project CLAUDE.md so every session has the conventions in view:

# MCP rules

## Config scope
- Team-shared servers live in committed .mcp.json (project scope)
- Personal servers use `claude mcp add --scope user`
- After editing .mcp.json or adding a server, RESTART the session (config reads at start)

## Server entries
- Every server entry declares its required env vars in the `env` block explicitly
- NEVER assume a server inherits a shell-exported variable; declare it in config
- Prefer absolute paths for the command when PATH differences are a risk

## Verifying a server
- `claude mcp list` shows connected vs failed servers and is the first diagnostic
- `claude --debug` surfaces server stdout/stderr and the connection handshake
- A failed server is run directly in a plain terminal to reproduce the error

## When a server will not connect, check in order
1. Right scope?            (claude mcp list shows it)
2. Command installed?      (run the launch command directly)
3. Env vars present?       (declared in the entry, real values)
4. Session restarted?      (config is read at start)
5. Project server approved? (trust gate for committed .mcp.json)
6. Logs read?              (claude --debug for the real error)

That ordered checklist is the whole troubleshooting flow compressed into something every session sees. The two habits that prevent the most pain are: restart after any config change, and declare env vars explicitly in the server entry rather than relying on the shell. For the wider configuration model these fit into, Claude Code permissions covers the trust and safety layer that the project-server approval gate is part of.

When to escalate

Most MCP connection failures are one of the six causes above and resolve in minutes. Escalate beyond your own config when:

• The launch command runs cleanly in a terminal and all env vars are correct, but claude --debug shows the server completing startup yet Claude still sees no tools. That points at the server's MCP implementation, not your setup, raise it with the server's maintainer with the debug log attached.
• A previously working server starts failing after you upgraded Claude Code or the server package. Note the versions and check the server's issue tracker; a protocol or API change is the likely cause, and the fix is a version pin or an update on one side.
• The handshake times out only on a slow network or a large dataset, never locally. That is a readiness/performance issue in the server worth reporting with the conditions that trigger it.

When you do escalate, bring the claude --debug output and the exact server config (secrets redacted). That turns a vague "it will not connect" into a reproducible report a maintainer can act on. For everything short of that, the ordered checklist resolves it. The common case is never a deep bug, it is scope, a missing variable, or a session that needs a restart.

If you are still setting things up, Claude Code MCP setup is the step-by-step, and Claude Code MCP servers covers which servers are worth connecting in the first place.

Get Claudify. A complete Claude Code operating system with MCP servers pre-configured and documented so connection issues do not slow you down.