Why my MCP server won't connect — 4 causes, most common first

The symptom is familiar: you ran the add command, it replied "Added…", and the agent has no new tools. Or the list shows a red ✘ Failed to connect.

First thing to know: "Added" does not mean the server works. It only means a line got saved to your config. Launching and connecting happen later — and that's where things actually break.

Below are four causes by frequency. Start at the top: the first covers more cases than the rest combined.

Cause 1: you added the server in a different folder

The most common one — and not a malfunction at all.

By default a server is added at local scope: it's tied to the project you ran the command from. Move to another folder, start the agent, and it's honestly not there.

How to check. Go back to the folder where you added it and run:

claude mcp list

If the server shows up there but not in your working project, that's your diagnosis.

How to fix. Decide where you need it and re-add it with the right scope:

claude mcp add --scope user --transport http name https://address/mcp

--scope user puts it in all your projects. --scope project writes a .mcp.json in the project root — commit it and the whole team gets it.

A separate trap. If you edited the config by hand, check the path. Exactly two files are read: ~/.claude.json and .mcp.json in the project root. Paths like ~/.claude/mcp.json or ~/.claude/config/mcp.json look plausible, but nothing reads them. The file exists; the server doesn't.

Cause 2: the server doesn't start

Status ✘ Failed to connect or ✘ Connection error. Two different situations here, checked in different ways.

Local server: run its command by hand. Type exactly what you put after the -- into your terminal:

npx -y @playwright/mcp@latest

What you see is the diagnosis:

• It starts and hangs, waiting for input. That's correct behaviour: the server is fine, the config isn't. Usually you forgot the -- separator in the add command, which scatters the arguments. Compare with claude mcp get <name>, which shows the command the agent actually tries to run.
• It errors out. Read the text — it names what's missing: no Node.js, no browser, package not found.

Hosted server: knock on the address.

curl -I https://address/mcp

Read the answer like this:

• 404 or 405 — the server is alive. Many MCP endpoints answer POST only, so this is a normal "the address is reachable" sign.
• 401 or 403 — alive, but it wants authentication. Add a token: --header "Authorization: Bearer your_token".
• Silence or a timeout — the address or your network. Check the whole URL with claude mcp get <name>.

And one frequent small thing when pasting a token: a stray space or newline at the end. Looks identical, behaves differently.

Cause 3: thirty seconds weren't enough

Symptom: first attempt shows ✘ Failed to connect, and a minute later the same server is suddenly ✔ Connected.

That's the startup timeout. The default allowance is 30 seconds, and on its first run npx is still downloading the package.

How to check. Wait half a minute and re-run claude mcp list. If it turns green, that was it.

How to fix. If the package is heavy and keeps missing the window, raise the limit (in milliseconds):

MCP_TIMEOUT=60000 claude

Cause 4: connected, but zero tools

Green status, yet the agent says it can't do anything. This isn't a connection problem any more — the server started but registered no tools.

Nearly always one reason: a missing environment variable, usually an API key. Without it the server comes up with nothing to offer.

How to check. Run /mcp inside a session, select the server and look at its tool list. Empty confirms the diagnosis.

How to fix. Check the server's docs for the variables it expects and pass them with the flag:

claude mcp add name --env API_KEY=your_key -- npx -y package

Order matters: --env goes before the -- separator, or the flag gets swallowed by the server command. For what these variables are in general, see our piece on environment variables.

I edit .mcp.json and nothing changes

That file is read at session start. Quit and reopen, and the edits land.

If it's still empty after a restart, run claude mcp list in your shell and look for a parse warning: a malformed entry is skipped silently, but the warning names the offending field. The other servers keep working meanwhile — which is why "some show up, some don't" looks so mysterious.

The server sits on "Pending approval"

That's not an error. It marks servers coming from the project's shared .mcp.json: you approve them once inside a session. If you rejected one by mistake, reset the decisions with claude mcp reset-project-choices.

Where to start when nothing helped

Go back to basics and walk the path again with a server you know works — the step-by-step setup takes five minutes. If a clean example connects and yours doesn't, the problem is that specific server, and its documentation is the next thing to read. For what MCP is and why servers are built this way, see the basics.