Kingy AI
Subscribe, 2.2M subscribersWork with Kingy
Skip to content

Kingy / AI Fix Finder

← All fixes

Claude Code MCP server "Failed to connect": how to fix it

Check this fix ↓

Claude Code says ✘ Failed to connect for an MCP server? Match the message (ENOENT, Connection closed, timed out) to a fix Kingy confirmed on Claude Code 2.1.318.

kingy tested Checked 2026-11-06

Fix it

  1. Run claude mcp list and read the words after "Failed to connect —". claude mcp get <name> shows the same text on its Issue: line.

  2. Find that message in the table below. Each one has a different cause and fix.

  3. Remove the server (claude mcp remove <name>), then add it again with the fix. Put the server name straight after add, and any options such as -e KEY=value after the name:

    claude mcp add <name> -e KEY=value -- <command>

  4. Check it worked: claude mcp list should now show ✔ Connected for that server.

Status:

  • Errors reproduced by Kingy on Claude Code 2.1.318 (the npm latest release on November 6, 2026) and 2.1.283, on macOS. That covers every message on this page.
  • Fixes confirmed on both versions, each turning the same server from "Failed to connect" to ✔ Connected.
  • Not tested: Windows, Linux, remote (HTTP/SSE) servers, and servers that need sign-in.

Which message do you have?

Message after "Failed to connect —" What it means Fix
ENOENT: no such file or directory, posix_spawn '<path>' Nothing exists at the path you gave Fix the path
ENOENT: Executable not found in $PATH: "<name>" Claude Code can't find a program with that name Use the full path
CONNECTION_CLOSED: Connection closed The server started, then quit Run it yourself to see why
MCP server "<name>" connection timed out after 30000ms The server took longer than 30 seconds to start Give it more time

The setup command can also fail before anything connects. If claude mcp add itself says error: missing required argument 'commandOrUrl', see that section.

ENOENT: no such file or directory, posix_spawn

ENOENT means "no such file". posix_spawn is how Claude Code starts the server program. So Claude Code tried to start a program at the path you gave, and nothing is there. Possible reasons include a typo, a moved folder or a relative path. Kingy tested only a path that doesn't exist.

Fix:

  1. Check the path in a terminal: ls -l /path/to/server. "No such file or directory" means the path is wrong.
  2. Remove the server and add it again with the correct full path.

In our test, the same server went from this error to ✔ Connected once it was added with a correct full path.

On Claude Code 2.1.283 the message starts ENOENT: ENOENT: (the word appears twice). On 2.1.318 it appears once. The fix is the same.

ENOENT: Executable not found in $PATH

You gave a bare command name. $PATH is the list of folders your system searches for programs, and Claude Code didn't find that name in any of them. Possible reasons:

  • The server isn't installed.
  • Claude Code was started with a different PATH from the terminal where the server works.

Fix:

  1. In a terminal where the server works, run which <name>. If it prints a path, that's the full path.
  2. Remove the server and add it again with that full path: claude mcp add <name> -- /full/path/to/server.
  3. If which prints nothing, the server isn't installed (or isn't on your PATH). Install it first.

In our test, a bare name that failed connected once it was added with its full path. It also connected when Claude Code was started with the server's folder on its PATH.

CONNECTION_CLOSED: Connection closed

The program started, but quit before it finished connecting. In our test, neither claude mcp list nor claude mcp get showed the server's own error message, only CONNECTION_CLOSED: Connection closed.

Fix:

  1. Run the exact same command yourself in a terminal, to see any error it prints when it quits. Our demo server printed Error: DEMO_API_KEY is not set.

  2. If it needs an environment variable (an API key, for example), remove the server and add it again with -e, name first:

    claude mcp add <name> -e MY_API_KEY=your-value -- <command>

  3. Run claude mcp list. In our test, the same server went from "Connection closed" to ✔ Connected.

MCP server "<name>" connection timed out after 30000ms

The server didn't finish starting within 30 seconds, which is Claude Code's default. Anthropic's MCP quickstart says a server's first run can be slow while npx downloads the package.

Fix: start Claude Code with a longer limit, in milliseconds. This is the example from Anthropic's MCP quickstart:

MCP_TIMEOUT=60000 claude

In our test, a demo server that takes 40 seconds to start:

  • timed out at the default 30 seconds,
  • then showed ✔ Connected with MCP_TIMEOUT=60000.

claude mcp list reads the same setting. If a server still times out with a long limit, it may never be answering. Run its command yourself, as in the section above.

error: missing required argument 'commandOrUrl'

This comes from claude mcp add, not from the server. It appears when -e KEY=value comes before the server name, as in:

claude mcp add -e KEY=value myserver -- command

The -e option accepts several values, so it treats your server name as another variable, and then finds no command. Nothing is added: in our test, claude mcp list then said "No MCP servers configured".

Fix: either form works. Kingy tested both on both versions:

  • Put the name first: claude mcp add myserver -e KEY=value -- command
  • Or put another option between -e and the name, as Anthropic's MCP guide does: claude mcp add -e KEY=value --transport stdio myserver -- command

What we tested that did NOT cause the error

A banner line on standard output. A local (stdio) MCP server talks to Claude Code over its standard output ("stdout"). We tested a server that printed one line of text there before starting properly, and it still showed ✔ Connected, on both versions.

The MCP specification says a server must not write anything but MCP messages to stdout, and may write logs to standard error ("stderr"). So keep logs on stderr anyway. We tested only a single line before start-up, and other output may still break the connection.

How Kingy tested this

  • Setup: each case ran in a throwaway home folder, with no Claude login and no API key. We used small demo servers, one per cause:
    • a missing file
    • a command that is installed but not on Claude Code's PATH
    • a server that quits when its key is missing
    • a server that starts after 40 seconds
    • a server that prints a banner first
    • a working server
  • Steps: for every error, we triggered it, applied the fix to the same server, and checked again.
  • Evidence: the error text above is copied from those runs. The script, both raw logs and the demo servers are kept with this page's evidence.

Not covered here

  • Remote (HTTP/SSE) servers and sign-in problems. Anthropic's errors page covers messages such as "needs you to sign in again".
  • Windows and Linux. Not tested by Kingy.
  • On Windows, Anthropic's quickstart sets the time limit in PowerShell with $env:MCP_TIMEOUT = "60000"; claude.

Sources

  • Kingy lab logs, 2026-11-06 (UTC): Claude Code 2.1.318 and 2.1.283, macOS 26.3.
  • Anthropic, Connect Claude Code to tools via MCP. Read 2026-11-06 for:
    • the -e/--env option and its ordering note,
    • MCP_TIMEOUT,
    • the claude mcp list statuses and the claude mcp get Issue line.
  • Anthropic, MCP quickstart. Read 2026-11-06 for: the 30-second default, the slow first npx run, and the MCP_TIMEOUT=60000 claude and PowerShell examples.
  • Anthropic, Claude Code errors. Read 2026-11-06. It sends "MCP server failed to connect" to the MCP guide.
  • Model Context Protocol, Transports specification (2025-06-18). Read 2026-11-06 for the stdout and stderr rules for stdio servers.