Table of Contents

You set up an MCP (Model Context Protocol) server, but opening /mcp shows it stuck in a state like this — sound familiar?

/mcp

  filesystem      ✓ connected      (12 tools)
  github          ✗ failed
  notion          △ needs authentication
  my-server       ⏸ pending approval

MCP lets Claude Code work with external tools and data. If a connection fails, do not diagnose it from the status alone: check the connection method and error details together. This article walks through local startup, remote communication and authentication, configuration, and approval.

The essentials: (1) Read the status and details with /mcp and claude mcp get <name>. (2) failed can occur with both local and remote servers. For stdio, check the command and environment variables; for HTTP, check the URL, network, server response, and authentication. (3) If the cause is unclear, inspect connection logs with claude --debug=mcp. Change only what the actual error points to, then reconnect to verify the result.

CLAUDE CODE · MCP STATUS

Find the cause from status and details

— for failed, check the connection method and error details too

$ /mcp
✓ filesystem connected · 12 tools
✗ github failed → check Issue
△ notion needs auth → check auth method
⏸ my-server pending → approve it

✗ failed = connection failed, △ needs auth = check authentication, ⏸ pending = waiting for approval.
failed alone does not identify the cause. Read the connection method and error details.

1. What this error is telling you

For example, you may see the following error in a log. Do not assume the server failed to start from this wording alone; check the preceding log entries too.

MCP error -32000: Connection closed

MCP error -32000: Connection closed indicates that the connection closed. The MCP TypeScript SDK assigns -32000 to ConnectionClosed. Check preceding logs to find what closed it, such as a server exit or a lost connection. The wording alone cannot tell you whether the process exited before initialization or the connection dropped afterward. See the SDK connection-close handling.

Do not assume similar error messages have the same cause. Errors vary by client, version, and server. When using advice for another tool, check whether it applies to your connection method and logs.

Bugs outside your configuration are another possibility. For example, Issue #20713 contains a user report of disconnection during initialization with Claude Code 2.1.19 on macOS. Do not treat a user’s diagnosis as a cause confirmed by Anthropic or a current bug affecting every environment. Include your OS, version, connection method, and logs with secrets removed when reporting an issue.

MCP servers commonly use two connection types. (1) stdio (local) — Claude Code launches the server's command as a subprocess on your machine and talks over standard I/O. (2) HTTP (remote) — it connects to a cloud server by URL (the older SSE is deprecated). What "won't connect" means depends heavily on the type.

For local (stdio) servers, check for a missing command, missing variables, a server exiting, or logs mixed into stdout. For remote (HTTP) servers, check for an incorrect URL, network problems, 5xx responses, timeouts, and authentication. Configuration location, syntax, and scope matter for both. Do not assume failures are “almost always authentication” or “almost always paths” without evidence of their frequency.

First, record the status and error details, and identify whether the connection uses stdio or HTTP. Changing several settings at once makes it hard to tell which change helped. Use the following table as a starting point, then investigate one relevant cause at a time.

2. Read the status with /mcp first

Run /mcp in session (or claude mcp list / claude mcp get <name> from the shell) to see each server's state. The main statuses and meanings:

StatusMeaningWhere to look first
✓ connectedConnected. Tool count shown beside itIf tools are expected but the count is 0, check exposed capabilities, permissions, and logs
✗ failedConnection to a local or remote server failedIssue details and connection method. For HTTP, also check communication, server responses, and fixed authentication headers
△ needs authenticationSign-in or additional permissions needed. Check the configured authentication method tooFor OAuth, authenticate through /mcp. For custom auth, check the credential source; for claude.ai connectors, check connector settings
⏸ pending approvalA project .mcp.json server waiting for approvalApprove in /mcp. If wrongly declined: claude mcp reset-project-choices
✗ rejectedA project server rejected by configurationCheck disabledMcpjsonServers and managed policies. Use reset-project-choices to reset your own approval choices

failed alone cannot distinguish local startup from remote communication problems. Read any HTTP code or error body in Issue: from claude mcp get <name> or in the details under /mcp. A fixed Authorization header rejected with 401/403 during connection also produces failed. Also, zero tools is not necessarily an error for a server that only provides resources or prompts. First check whether it is intended to provide tools. See the official server-status details.

3. Main causes of failure and fixes

These checks help investigate connection failures and configuration mismatches. Start with the items relevant to your connection method.

ROOT CAUSES

Checks by connection method

1) Path / PATH
Relative paths resolve against the launch directory and drift. Use absolute paths for local scripts. A missing executable gives spawn ... ENOENT.
2) Env vars not passed
Set stdio server-specific variables in that server’s env. The env in settings.json also applies to the session and child processes, so check those values too.
3) Startup timeout
If logs confirm a startup timeout, adjust MCP_TIMEOUT (ms). In Bash: MCP_TIMEOUT=10000 claude. In PowerShell, set $env:MCP_TIMEOUT='10000', then launch claude.
4) Config location / JSON
A project .mcp.json goes at the project root (not under .claude/ or in settings.json). An undefined ${VAR} without a default raises a warning and remains as literal text.
5) Polluting stdout
A stdio server that writes logs to stdout corrupts the protocol. Send logs to stderr.
6) Remote auth
If OAuth sign-in is needed, authenticate through /mcp. Note that a rejected fixed authentication header is reported as failed.

For local servers, check the command, environment variables, and logs.
For remote servers, check the URL, communication, server response, and authentication, following the actual error.

You can share a project .mcp.json, but do not commit secret values directly. For example, reference ${API_KEY} and set the required value in each environment. Some protected variable names, including Claude Code’s own credentials, resolve to empty strings in remote URLs and headers; check the official expansion rules. Interactive sessions request approval for project servers. In contrast, claude -p and the SDK normally load them without that prompt. See the official project scope documentation for rejection settings and other conditions. MCP basics and A2A are also related.

4. Check npx startup on Windows

If Windows reports spawn npx ENOENT, first check the executable and PATH with where.exe npx. Also check whether Node/npm works and the specified package can start. The official Node documentation explains that .cmd files cannot be executed directly and shows ways to start them through a shell or cmd.exe. However, this does not mean specifying npx directly fails in every Claude Code environment.

If the launch method is the cause: try cmd.exe /c

If the problem is how the .cmd file starts, try this form. Replace the package name with the one in the server’s official instructions:

{
  "command": "cmd.exe",
  "args": ["/c", "npx", "-y", "@scope/your-mcp-server"]
}

WSL also requires Node, packages, and environment variables on the Linux side. Switching to WSL does not guarantee a fix. Check the server’s supported environments and your Claude Code version too.

5. The diagnostic workflow

When the cause is unclear, work top-down. The trick is to confirm the server runs standalone before blaming Claude Code.

DIAGNOSE

Isolate it top-down

1
Use /mcp and claude mcp list / get to check the status, and read Issue: and the connection method too.
2
Use claude --debug=mcp to check MCP initialization and connection logs. For stdio servers, check stderr too.
3
For stdio, test a standalone launch with the same command and variables as the configuration. For HTTP, check the URL, network path, and response code.
4
Verify the server alone with MCP Inspector (npx @modelcontextprotocol/inspector) — inspect its tool list and invoke tools in a UI.
5
Reconnect after changes and try the operation you need. If failure continues, report the version, connection method, and logs with secrets removed.

A successful standalone launch is different from a successful MCP connection and operation.
Protocol compatibility, permissions, tool discovery, and client bugs can still cause problems after startup.

Note: adding too many MCP servers makes tool definitions eat the context (especially with always-load setups). Claude Code defers tool definitions via tool search by default, so the impact is small, but it is still wise to disable servers you do not use. Overloading the context can even trigger Prompt is too long.

6. Prevention checklist

Habits to avoid getting stuck on MCP connections.

(1) Check the actual paths of stdio executables and scripts. (2) Distinguish stdio variables from HTTP authentication headers, and keep secrets out of shared files. (3) On Windows, check where.exe npx and Node/npm; try cmd.exe /c only when the launch method is the problem. (4) Put .mcp.json at the project root and check JSON syntax, variables, and approval. (5) Send stdio logs to stderr, not stdout. (6) Make one change at a time, then reconnect and test the required operation.

Summary

Investigate Claude Code MCP connection errors using the status, connection method, and error details together. failed is not limited to local startup failures: HTTP communication failures and rejected fixed authentication headers can also produce it. needs authentication points you toward authentication checks, while pending approval points you toward approval for a project server.

Work through these steps: read the status and Issue: → check logs appropriate to the connection method → test standalone operation or communication → reconnect and verify the operation. Select the debug category with claude --debug=mcp. Add --debug-file ./claude-mcp-debug.log to save the logs. Remove secrets before sharing them. Related: What is MCP, Monetizing MCP servers, Claude Code error roundup.

FAQ

Q. /mcp shows failed. Where do I start?
A. Check the connection method and Issue:. For stdio, inspect the command, path, environment variables, and stderr; for HTTP, inspect the URL, network, server response, and authentication. A fixed Authorization header rejected with 401/403 during connection also produces failed, so do not assume it is a local startup problem.

Q. It says "needs authentication" and the tools do not work.
A. Check the configured authentication method first. For an OAuth server, authenticate through /mcp and check the required permissions. With a custom headersHelper, this state can also appear when a tool call returns 401/403 and retrying with refreshed credentials fails. If the helper supplies an Authorization header, Claude Code does not switch to OAuth: fix the credential source and the value it returns, then reconnect. Anthropic-hosted connectors such as Microsoft 365, Gmail, and Google Calendar that do not support local OAuth must be connected in claude.ai's connector settings. See the official custom-authentication documentation.

Q. My npx server will not connect on Windows.
A. Check where.exe npx and Node/npm, and try starting the same package with the same arguments. If the problem is how the .cmd file launches, you can use cmd.exe /c npx .... WSL also requires a working Linux-side environment. Changing operating systems alone does not guarantee a solution.

Q. It is connected but shows 0 tools.
A. Check whether that server is designed to provide tools. Zero tools is not necessarily an error if it only provides resources or prompts. If tools should be available, inspect exposed capabilities, permissions, server settings, and logs, then reconnect. Send stdio diagnostic logs to stderr, not to the stdout stream used for the protocol.

Q. I configured a server but cannot use it.
A. Check that the shared project .mcp.json is at the project root, then check syntax, scope, and approval status. An undefined ${VAR} without a default raises a warning and remains literal text as configuration is loaded, which can cause startup or authentication failures. Specify type for HTTP configurations too. Repeating approval alone will not resolve rejection settings or managed policies.

Configuration and command references: env settings, CLI reference, MCP connection reference.