← Blog · 2026-10-18

Claude Code MCP Server Not Connecting? 12 Causes and Fixes

Shortcut: our free .mcp.json builder writes a valid MCP config for stdio, HTTP, SSE or WebSocket servers, always sets type on remote entries, and prints the matching claude mcp add command with the -- in the right place, so several of the problems below can't happen. It runs in your browser.

An MCP server gives Claude Code tools from outside your project: a database, Notion, GitHub, Stripe and so on. When one "doesn't work", it's one of three things: Claude Code never read the server's config, it read it but couldn't start or reach the server, or the server connected and isn't giving Claude any tools. Work through the checks below in order.

First: what does Claude Code say about the server?

From your shell, run claude mcp list. Each server gets a status such as ✔ Connected, ! Needs authentication or ✘ Failed to connect. Then run claude mcp get <name> for the one that's broken: on a failure it shows an Issue: line with the HTTP status or error code and any error text the server sent back (Claude Code v2.1.219 or later). Inside a session, /mcp shows the same statuses and the same Issue: detail.

If the server isn't in the list at all, start at cause 1. If it says Pending approval, Rejected or Disabled, go to cause 3. If it says Failed to connect, start at cause 6. If it's connected but Claude can't use it, go to cause 12.

Not loaded: 5 reasons the server never shows up

.mcp.json is in the wrong place or uses the wrong key. A project's MCP config goes at the repository root as .mcp.json, not inside .claude/. The servers sit under a top-level mcpServers key. A file copied from VS Code's mcp.json, which uses a servers key, never loads.
You put mcpServers in settings.json. Claude Code's settings.json doesn't read an mcpServers key, so servers there never appear. Put project servers in .mcp.json, or add personal ones with claude mcp add --scope user, which stores them in ~/.claude.json.
The project server is waiting for approval, rejected or turned off. Claude Code asks once before it uses servers from a project's .mcp.json. If you dismissed that prompt, the server stays at ⏸ Pending approval until you approve it from /mcp. In a folder you haven't trusted yet, approvals committed to the repo's .claude/settings.json are ignored, so run claude there and accept the trust dialog. A server listed in disabledMcpjsonServers in any settings file shows ✘ Rejected, and one you toggled off in /mcp shows ⊘ Disabled for this project until you turn it back on there. To reset your approval choices, run claude mcp reset-project-choices.
You added it in a different project, or another scope wins. claude mcp add uses local scope by default, which loads the server only in the project folder you ran it from. Add --scope user to get it everywhere, or --scope project to share it in .mcp.json. If the same name exists in more than one scope, Claude Code uses the whole entry from the highest one (local, then project, then user, then plugins, then claude.ai connectors) and doesn't merge fields, so a stale local entry can hide the one you just edited. claude mcp list warns about the conflict; remove the extra with claude mcp remove <name> --scope <scope>.
The name is reserved. Claude Code skips a server named after one of its built-ins, such as workspace, claude-in-chrome or computer-use, and shows a warning asking you to rename it. Server names should use only letters, numbers, hyphens and underscores.

Failed to connect (local stdio servers): 4 reasons

The -- separator is missing or --env is in the wrong spot. For a local server, everything after -- is the command that starts it: claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server. Without --, Claude Code tries to read the server's own flags, such as -y or --port, as its own. And if the server name comes straight after --env, the CLI reads the name as another KEY=value pair and rejects it, so put another option such as --transport stdio between them.
The command uses a relative path. Relative paths in command or args resolve against the folder you launched Claude Code from, not the folder that holds .mcp.json, so the server starts from one directory and fails from another. Use absolute paths for local scripts. Programs on your PATH, like npx or uvx, work as written.
An environment variable is missing or has hidden whitespace. Set the variables a server needs in its own env block in the config instead of relying on your shell. A ${VAR} reference to a variable that isn't set and has no ${VAR:-default} fallback stays as the literal text ${VAR}, and claude mcp list warns about it. Claude Code also warns when a pasted value carries a hidden leading or trailing space or newline, but it uses the value as written, so delete the whitespace yourself.
The server takes too long to start. A slow first npx download or a heavy server can miss the startup window. Raise it with the MCP_TIMEOUT environment variable, in milliseconds: MCP_TIMEOUT=10000 claude allows ten seconds.

Failed to connect (remote servers): 2 reasons

The entry has a url but no type. Claude Code reads an entry with no type as a local stdio server, so a url-only entry copied from another app's config fails. Add "type": "http" (or "sse" if the service says so). For a wss:// address use "type": "ws" through .mcp.json or claude mcp add-json, because claude mcp add --transport doesn't accept ws.
The credential is missing, expired or reads as empty. ! Needs authentication means you haven't signed in or the sign-in expired: run /mcp, pick the server and sign in, or run claude mcp login <name> from your shell. Sign-ins are stored per endpoint, so a second definition of the same server with a different URL needs its own sign-in. If you put a header like Bearer ${ANTHROPIC_API_KEY} in a remote server's config, the server receives an empty token and usually answers 401: Claude Code deliberately reads its own and your cloud provider's credentials (and others such as NPM_TOKEN and HTTPS_PROXY) as empty in remote url and headers. Copy the key into a variable with a name of your own, such as MY_SERVICE_KEY, and reference that.

Connected, but Claude can't use it

It shows zero tools, or it dropped mid-session. A server that's connected with zero tools started but isn't returning a tool list. Select Reconnect in /mcp. If the count stays at zero, run claude --debug=mcp and read the server's error output in the debug log at ~/.claude/debug/<session-id>.txt. Claude Code reconnects a remote server that drops (up to five tries) but doesn't restart a local stdio server on its own, so reconnect that one from /mcp. To retry every failed server at once, run /mcp reconnect all (v2.1.284 or later in the terminal).

Still stuck?

Run /doctor inside Claude Code (or claude doctor from your shell if it won't start) for a checkup of your installation and settings that flags invalid settings files. Then start a session with claude --debug=mcp, reproduce the failure, and read what the server printed in ~/.claude/debug/<session-id>.txt. The server's own error message usually names the missing package, key or port.

A minimal config that loads

{
  "mcpServers": {
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    },
    "airtable": {
      "command": "npx",
      "args": ["-y", "airtable-mcp-server"],
      "env": { "AIRTABLE_API_KEY": "${AIRTABLE_API_KEY}" }
    }
  }
}

Save it as .mcp.json in your project root, set AIRTABLE_API_KEY in your shell, start claude in that folder and approve both servers. Then run /mcp to sign in to Notion. The same two servers from the command line:

claude mcp add --transport http notion https://mcp.notion.com/mcp
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server

Facts on this page come from Anthropic's MCP documentation, debug your configuration guide and error reference. This guide isn't affiliated with Anthropic.