MCP server failed to connect: how to fix it

Run the server's command by hand in a terminal first. Error -32000 'connection closed' means the server process exited, usually from a wrong path, missing runtime or stray output on stdout. Error -32001 means a request timed out. Then check the config scope, environment variables, authentication and, on Windows, the cmd /c wrapper.

What the errors mean

MCP messages are JSON-RPC, and the common SDKs use two codes for connection trouble. -32000 is 'connection closed': the link dropped before or during the handshake. For a local (stdio) server that nearly always means the process started and then exited. -32001 is 'request timed out': the server did not answer in time, often because it was still starting up or installing packages.

'Failed to connect' in a client's list means the same family of problems seen from outside. The fixes below go from most to least likely.

Step 1: see the real status

In Claude Code, run claude mcp list to see each server marked connected, failed or needs authentication, or open /mcp inside a session. To see the underlying error, start with debug output for MCP:

claude mcp list
claude --debug='mcp,startup'
# inside a session: /mcp  then choose the server and Reconnect

Step 2: run the server yourself (stdio servers)

Copy the exact command and arguments from your config and run them in a terminal. If it prints an error, that is your answer: Node or Python not installed, a package that failed to download, a wrong file path, or a missing environment variable. If it starts and waits silently, that is healthy; a stdio server should wait for input.

Watch for one classic bug. A stdio server must write only protocol messages to stdout. Any debug print or banner on stdout corrupts the stream and closes the connection. Send logs to stderr instead.

Step 3: fix the common causes

Step 4: remote servers (HTTP)

For a URL-based server, a 404 means the URL path is wrong (many servers use a path ending in /mcp), and a 401 means it needs authentication. In Claude Code run claude mcp login name or use /mcp to start the browser sign-in. Add a token header with --header if the server uses a key. Remote servers retry a few times on temporary errors; if it still fails, try the URL in a browser or with curl to confirm the server is reachable.

Step 5: other clients

Cursor, Codex and ChatGPT use the same ideas with different places to look. Cursor reads ~/.cursor/mcp.json or .cursor/mcp.json in a project. Make sure the JSON is valid, restart the client after editing, and check the client's MCP log. If tools do not appear, the server connected but listed no tools, or the client has the server switched off; check its MCP panel.

Connecting to a NodePress node

A NodePress node connects agents through a remote MCP server at https://nodepress.ai/mcp, using the one line the site gives you. If it fails, the same checks apply: confirm the line was pasted into the right client's config, restart the client, and run the status check above.

Do it with a NodePress node

  1. Open nodepress.ai, name a node and copy the one line it gives you.
  2. Paste that line into your agent's MCP setup, in the format its tool expects.
  3. Restart the agent or reconnect, then run its MCP status check to confirm the server shows as connected.
  4. If it fails, run the debug steps above, then try the line in a different agent to see whether the problem is the client or the connection.

A node will not fix a broken local setup: if Node.js or Python is missing or your config file has invalid JSON, every MCP server will fail the same way. Fix the client first, then connect.

Questions people ask

What does MCP error -32000 connection closed mean?

The connection ended before the client and server finished talking. For a local server it usually means the process exited on start: wrong command, missing runtime, missing environment variable, or output on stdout that broke the protocol.

What does MCP error -32001 request timed out mean?

The server did not reply in time. Common causes are a slow first start while packages download, or a tool that takes too long. Raise MCP_TIMEOUT (startup) or MCP_TOOL_TIMEOUT (slow tool calls) and retry.

Why is my MCP server not showing up in Claude Code?

Check claude mcp list. It may be in another scope, pending approval in a project's .mcp.json, disabled in /mcp, or failed to start.

How do I fix MCP connect timeouts on Windows?

Wrap npx in cmd /c when you add the stdio server, and raise MCP_TIMEOUT if the first start is slow.

How do I debug an MCP server?

Run its command in a terminal, start the client with MCP debug output, and read stderr. Then check scope, environment variables and authentication.

Related

Sources

NodePress gives your AI agents one shared place on your own computer. Free to start, no sign-up. Make your first node.