How to Fix Claude Code MCP Failed to Connect Errors

When Claude Code reports Failed to connect, MCP startup failed, -32000: Connection closed, or a server connects but its tools never appear, debug the connection in this order: configuration and approval, executable and environment, startup time, protocol output, then the MCP initialize handshake. That sequence separates a process that never started from one that started but could not speak MCP.

Do not begin by reinstalling every package or raising every timeout. First identify the failing stage, change one variable, and repeat the same connection check. You are done when claude mcp list reports the server as connected, /mcp shows its tools, and one read-only tool succeeds after restarting Claude Code.

Match the Error to the First Check

If the browser login fails with localhost refused to connect, redirect_uri_mismatch, or invalid state, the server has reached the authentication stage. Use the MCP OAuth callback troubleshooting guide rather than changing startup settings.

Prerequisites

You need:

1. The MCP server name as Claude Code knows it.

2. Access to the relevant .mcp.json or user configuration.

3. The exact command, arguments, environment variables, or remote URL used by the server.

4. A terminal that can run Claude Code and the MCP server command.

5. Sanitized stderr or server logs. Never paste access tokens, API keys, cookies, or full OAuth callback URLs into an issue.

The commands below assume a current Claude Code release. Run claude --version and compare behavior with the current official MCP reference before relying on version-specific timeout or reconnection behavior.

Step 1: Confirm Claude Code Loaded the Configuration

List configured servers from the same project directory where the failure occurs:

claude mcp list
claude mcp get my-server

Expected result: my-server appears with the transport, scope, command or URL you intended.

If the server is missing, check which scope owns it:

• local applies only to the current project and is stored in your user configuration;

• project is shared through .mcp.json;

• user applies across projects.

A project-scoped server can also remain Pending approval until you open Claude Code interactively and trust the workspace. Do not work around the trust prompt by committing a setting that approves the repository's own server. Approve only a server and repository you have reviewed.

For a remote server, verify that the entry declares its transport. A configuration with a url but no type is invalid; use "type": "http" for Streamable HTTP. SSE is deprecated when HTTP is available.

Step 2: Run the Exact Stdio Command Outside Claude Code

For a local stdio server, copy the configured command and arguments exactly. First resolve the executable:

command -v node
command -v npx
node --version

On Windows PowerShell:

Get-Command node
Get-Command npx
node --version

Then run the server command directly. For example:

/absolute/path/to/npx -y example-mcp-server

Expected result: the process stays running and waits for MCP input. If it exits immediately, prints a stack trace, or cannot find a file, fix that failure before changing Claude Code.

An interactive shell and a process launched by a desktop app, IDE, service, WSL session, or SSH host can inherit different PATH, working-directory, and environment values. Use an absolute executable path when resolution differs. Use ${CLAUDE_PROJECT_DIR} or an explicit path for project files instead of assuming the server starts in a particular directory.

Do not put secrets in .mcp.json if the file is committed. Use Claude Code's supported environment configuration or a secret store, and confirm only that each required variable exists:

test -n "$EXAMPLE_API_KEY" && echo set || echo missing

That command does not print the secret.

Step 3: Distinguish a Crash From a Slow Startup

If the command stays alive but Claude Code times out during startup, measure how long it takes to become ready. Package downloads, cold Python environments, endpoint security scanning, or a first-run build can make a valid server start slowly.

Claude Code supports a startup timeout through MCP_TIMEOUT, in milliseconds:

MCP_TIMEOUT=10000 claude

Increase it only after confirming that the server eventually completes initialization. A longer timeout cannot fix a missing executable, an uncaught exception, invalid JSON-RPC, or a process that waits for interactive input.

Prefer installing the package ahead of time and pinning a reviewed version over downloading an unpinned package on every startup. If npx is involved, run the exact command once in the same environment to separate package installation time from MCP initialization time.

Step 4: Keep Stdio Output Protocol-Clean

With stdio transport, stdout carries MCP JSON-RPC messages. A banner, debug line, progress spinner, or dependency log written to stdout can corrupt the protocol and cause Connection closed or an initialize parse error.

Send diagnostic output to stderr instead:

console.error('MCP server starting');

Libraries should not print initialization messages to stdout. Also check wrappers and package managers, not just your server code: a shell profile, runtime banner, or child process can write the offending bytes before the server handles initialize.

Expected result: starting the server produces no ordinary stdout text while it waits for client protocol messages. Sanitized stderr may contain logs, but it must not contain credentials.

Step 5: Test the Initialize Handshake With MCP Inspector

The MCP lifecycle begins with initialize. The client proposes a protocol version and capabilities, the server responds, and the client sends an initialized notification. If the process stays alive but closes during this exchange, test it independently with the official MCP Inspector.

For a package-based stdio server:

npx -y @modelcontextprotocol/inspector \
  npx -y example-mcp-server

For a local Node.js server:

npx @modelcontextprotocol/inspector \
  node /absolute/path/to/server/index.js

In Inspector:

1. Connect with the same transport, command, arguments, and safe environment values.

2. Confirm capability negotiation succeeds.

3. Open the Tools tab and run tools/list.

4. Invoke one read-only tool with a valid minimal input.

5. Review the notifications and sanitized server logs.

If Inspector fails too, the problem is in the server, transport, or environment rather than Claude Code's project configuration. Common causes are an unsupported protocol version, a response with the wrong JSON-RPC id, a server that sends requests before initialization completes, or an exception while building the initial capability list.

Step 6: Check Remote HTTP Separately

For a remote server, confirm the configured URL resolves from the machine running Claude Code:

curl -i https://mcp.example.com/mcp

Expected result depends on the server: an unauthenticated protected server commonly returns 401 Unauthorized with discovery metadata, while a public endpoint may return a protocol-specific response. DNS failure, connection refusal, TLS validation errors, redirects to a login page, and HTML from a reverse proxy all belong to the HTTP path, not the stdio startup path.

Use Inspector with Streamable HTTP to test the same URL. Check that the reverse proxy preserves the MCP endpoint, HTTP method, headers, and streaming behavior. Claude Code retries certain transient HTTP startup failures, but authentication and not-found responses require a configuration change.

If authentication starts but the callback fails, return to the OAuth guide. Do not disable TLS verification or copy tokens into the URL to turn a transport failure into a security problem.

Step 7: Configure Tool Execution Timeouts Independently

A server that connects successfully and later fails during a tool call does not have a startup problem. Claude Code supports a per-server timeout in milliseconds in .mcp.json:

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "timeout": 600000
    }
  }
}

That example permits a ten-minute tool call. Set the limit from measured operation behavior and keep it bounded. Do not raise MCP_TIMEOUT to fix a tool that starts successfully and then performs long work; the two settings cover different phases.

Reproduce the Fix End to End

After each change:

1. Run claude mcp list and claude mcp get my-server.

2. For stdio, run the exact command manually and confirm it stays alive without ordinary stdout output.

3. Connect through MCP Inspector and complete initialize plus tools/list.

4. Start Claude Code from the affected project and open /mcp.

5. Invoke one read-only tool and verify its expected result.

6. Exit Claude Code, restart it from the same project, and repeat the read-only call.

The fix is verified only if connection, discovery, and a real tool call all succeed. A green process or open TCP port alone does not prove that the MCP handshake works.

Why This Sequence Works

An MCP connection has distinct boundaries: Claude Code must load and approve a configuration; the operating system must start or reach the server; the transport must carry uncorrupted messages; and both sides must complete initialization before tools can be discovered. The same error wording can surface at more than one boundary, so testing them in order prevents a timeout change from hiding a process or protocol bug.

Recent community reports repeatedly describe silent first-turn failures, Connection closed during initialize, and servers that work only after a slow cold start. Search results are fragmented across individual tools and issue threads. The durable fix is an ordered test that produces an observable result at every boundary.

Avoid Local MCP Startup Failures With Managed Capabilities

If your goal is to let a coding agent call a supported SaaS tool rather than develop a local MCP server, Aident Loadout provides searchable capabilities and keeps connection state in Vault. This removes local package startup, PATH, and stdio framing from that integration path; it does not remove the need to verify authentication and the remote operation.

If Aident is not installed, give your coding agent this instruction:

Follow https://aident.ai/SETUP.md

Then verify authentication and connections:

aident account auth status
aident vault vault --action status

Search for the read-only operation you need:

aident capabilities search \
  --query "list my latest project issues" \
  --types '["action"]' \
  --limit 5

Ready to replace one fragile local integration with a managed capability? Connect one tool with Aident Loadout and verify one read-only action end to end.

When to Refresh This Guide

Refresh this page when Claude Code changes MCP scopes, approval behavior, retries, or timeout variables; the MCP lifecycle changes its initialization contract; Inspector changes its launch syntax; or recurring reports identify a failure mode that this sequence cannot isolate. Preserve the stable URL and retest every command and expected result against current primary documentation.

Sources

• Claude Code MCP reference

• MCP lifecycle specification

• MCP Inspector guide

• Claude Code issue: MCP server connection failed

• Claude Code issue: -32000: Connection closed

• Reddit: usability failures found across popular MCP servers

• Aident: MCP API Keys vs OAuth

• Aident: Local vs Remote MCP Servers