MCP server "Failed to connect" or "Connection closed": how to fix it

You added an MCP server, and instead of a green check you see ✘ Failed to connect. The message is usually just Connection closed, which tells you almost nothing. This page shows how to find the real cause. Tested with Claude Code 2.1.278 in September 2026.

Step 1: See what Claude Code says

Run this in a terminal:

claude mcp list

Inside a Claude Code session you can type /mcp instead. Each server gets a status:

• ✔ Connected: working.
• ! Needs authentication: a remote server that wants you to sign in.
• ✘ Failed to connect: the server didn't start or didn't answer. Keep reading.
• ⏸ Pending approval: it came from a project's .mcp.json and you haven't approved it yet. Run claude in that project and approve it.

For more detail on one server, run claude mcp get <name>. It shows where the server is saved, the exact command, and the status.

Step 2: Why "Connection closed" is so vague

For a server that runs on your computer, "Connection closed" means the program exited right after starting. It doesn't say why. We tried two broken setups and got the identical message for both:

badpkg: npx -y this-package-does-not-exist - ✘ Failed to connect — CONNECTION_CLOSED: Connection closed
badcmd: not-a-real-command                 - ✘ Failed to connect — CONNECTION_CLOSED: Connection closed

One was a mistyped package name and the other was a program that isn't installed. Same message, different fixes. That's why you need the next step.

Step 3: Run the command yourself

Take the command from your config and paste it into a terminal. For this config:

"context7": {
  "command": "npx",
  "args": ["-y", "@upstash/context7-mcp"]
}

you would run:

npx -y @upstash/context7-mcp

A healthy server usually prints nothing, or a short "running" line, and then waits. Press Ctrl+C to stop it. If it prints an error, that's your answer. The two we saw:

npm error code E404
npm error 404 Not Found - GET https://registry.npmjs.org/this-package-does-not-exist

That means the package name is wrong. Check the spelling against the package's own page on npm.

not-a-real-command: command not found

That means the program isn't installed, or isn't on your PATH.

The usual causes

The package name is wrong or outdated

The most common one. Old tutorials name packages that have since been renamed or retired. As of September 2026, several older @modelcontextprotocol servers (GitHub, Brave Search, Postgres, Slack) are marked as no longer supported on npm. See the servers worth installing first for what to use instead.

Node.js (or uv) isn't installed

Servers started with npx need Node.js. Check with node --version. Servers started with uvx need uv.

A required key or variable is missing

Some servers exit immediately if their API key isn't set. If your config refers to an environment variable such as ${GITHUB_TOKEN} and that variable isn't set on your computer, Claude Code shows a missing-variable warning next to that server in claude mcp list and passes the literal text through instead. Set the variable in the terminal you launch Claude Code from, then start it again.

The first start is slow

The first time npx runs a server it may need to download it, which can take a while. If the server works when you run it by hand but times out in Claude Code, you can raise the startup limit:

MCP_TIMEOUT=30000 claude

The value is in milliseconds. On Windows PowerShell, set it first with $env:MCP_TIMEOUT = "30000", then run claude.

Windows: try wrapping the command in cmd /c

Claude Code's docs suggest wrapping npx as cmd /c npx ... for some Windows setups. On the Windows machine we tested, servers started fine with or without it, so treat it as a last resort: use it only if the command works when you run it by hand but Claude Code still can't start it. The config builder has an optional toggle for it.

You edited the wrong file, or the wrong scope

Claude Code reads servers from three places: local (this project, private to you), project (a .mcp.json file you can commit) and user (every project). If a server appears twice with different settings, or doesn't appear in the project you're in, check claude mcp get <name> to see which one you're looking at. To remove a server: claude mcp remove <name>.

Claude Desktop or Cursor

The same advice applies: run the server's command in a terminal first. Claude Desktop also needs a full quit and restart after any config change, and keeps logs you can read (see the setup guide for where).

Still stuck?

Re-generate the config with the free builder and compare it with yours. A missing comma, a stray quote or the wrong nesting is easy to miss by eye.