Based on each vendor’s official docs, checked November 11, 2026

MCP connection closed: find why a server will not connect

“Connection closed” can appear after a local process exits, when a client cannot complete a protocol exchange, or when a remote connection fails. Do not choose a fix from the wording alone. Start by recording the client, server, transport, exact error and the last successful step. This guide uses Claude Code for client-specific commands, checked against Anthropic’s MCP docs and the official MCP debugging guide on November 11, 2026; the diagnostic boundaries apply more broadly, but other clients have their own configuration formats. If the message is specifically spawn npx ENOENT, use the existing MCP spawn npx ENOENT guide. That is a narrower process-launch problem, not a reason to rewrite every remote MCP connection. For a first installation rather than a failure, use how to add an MCP server.

1. 1. Establish what is configured

   In Claude Code, the official management commands include claude mcp list and claude mcp get SERVER_NAME. Replace SERVER_NAME with the configured name. Inside a session, /mcp shows server status and supports authentication for remote servers that require OAuth. These are Claude Code commands, not universal MCP commands. A successful claude mcp add means the configuration was written; it does not prove that the server connected. The documented statuses distinguish a connected server, one needing authentication and one that failed to connect. Capture that distinction before reinstalling anything. Also confirm scope: a server configured for another project or user context may not be the server this session sees. For project .mcp.json entries, check the client approval step rather than assuming presence on disk means permission to start. Claude Code also reports configuration-only states such as pending approval, rejected, disabled for this project, or blocked by enterprise policy, without attempting a connection.

   claude mcp list
   claude mcp get SERVER_NAME
   # in a session:
   /mcp

2. 2. Separate local stdio from remote HTTP

   A local stdio server is a process the client starts. A remote HTTP server is an endpoint the client connects to. Those paths have different failure modes. A remote URL does not belong in an executable’s command field; a local launch command does not become an HTTP endpoint by renaming its fields. Claude Code’s current documentation recommends HTTP for remote servers. In Claude Code JSON configuration, a remote server needs an appropriate type; an entry with a URL but no type is interpreted as stdio and is a configuration error. The docs accept streamable-http as an alias for http. SSE is documented as deprecated, with HTTP preferred where available. Do not copy that statement into another client’s schema without checking its docs. The MCP config generator can help prepare a starting config, but the client and server documentation remain the authority. A syntactically valid JSON file can still describe the wrong transport or endpoint.

   {
     "mcpServers": {
       "notion": {
         "type": "http",
         "url": "https://mcp.notion.com/mcp"
       }
     }
   }

3. 3. For a local server, inspect startup before changing timeouts

   Check the executable, arguments, working directory expectations and required environment variables against the server’s official setup. A process that exits immediately cannot be repaired by waiting longer. Record its exit or startup error, then investigate that specific failure. An editor-launched process may not see the same environment as your interactive shell. Compare the executable path and required variable names without printing secret values into shared logs. Prefer a minimal reproduction with non-sensitive test data. Do not send a full environment dump to a public issue. Official MCP debugging guidance also notes that the working directory for a client-launched stdio server may be undefined, so prefer absolute paths in command, args and env files. For stdio transports, protocol messages use standard output. Official MCP debugging guidance directs server logging to standard error; a startup banner or debug print on standard output is a place to investigate.

4. 4. For a remote server, verify endpoint and authentication

   Use the server’s documented MCP URL, not merely its homepage or an arbitrary REST endpoint. Check the client’s selected transport against the server’s current instructions. A website loading in a browser does not establish that an MCP session can initialize. If Claude Code reports that authentication is required, use its documented /mcp authentication flow rather than pasting session cookies or copying tokens from browser storage. Confirm that you are signing into the intended server and account. Follow your organization’s access rules; do not weaken policy to make a connection test pass. For a network or certificate failure, capture the precise client error and ask the service owner or network administrator to verify the path. Do not disable certificate verification or open broad inbound access as a generic troubleshooting step. These are safety recommendations, not a claim that every connection failure is a firewall problem.

5. 5. Distinguish startup time from tool execution time

   Claude Code documents MCP_TIMEOUT for server startup. Its example MCP_TIMEOUT=10000 claude sets a ten-second startup timeout. Tool execution uses a separate setting: a per-server timeout value in milliseconds can override MCP_TOOL_TIMEOUT. Only consider changing the startup timeout after you have evidence that a valid server is simply slow to initialize. Increasing a tool-call timeout does not fix an incorrect launch command, missing authentication or malformed transport configuration. Likewise, a server can connect successfully and later fail on one tool call; that is a different stage of the investigation. Do not change both timeouts and several config fields at once. Record one hypothesis, make one bounded change and repeat the same test so you can identify what actually helped.

   MCP_TIMEOUT=10000 claude

6. 6. Reproduce with MCP Inspector when appropriate

   The official MCP debugging guide recommends Inspector as an interactive testing tool for stdio and Streamable HTTP. It can inspect tools, prompts and resources and help separate a server issue from a client integration issue. Use only a server you trust and test credentials you are permitted to use. A tool invocation may have side effects; start with a documented read-only operation rather than invoking every advertised tool. If Inspector works but your client does not, compare the transport, endpoint, authentication and environment rather than declaring the server universally healthy. If both fail at the same initialization stage, you have a more useful report for the server owner. Include the exact failure and the smallest safe reproduction, not an unsupported assertion that MCP itself is broken.

What “connection closed” usually means

“MCP connection closed” and “MCP server not connecting” describe the same kind of symptom: the client never reached a usable session, or the session ended before a tool call completed. The failure may still be missing or unapproved config, a process that never started or exited, the wrong transport, failed authentication, or a later timeout. This guide does not claim that a JSON-RPC error code such as -32000 always means the connection closed; match the exact log line before you change a setting.

Start with the last successful step rather than jumping to timeouts. Confirm the server process, the transport and type, and authentication, then rerun the same test. If the error is spawn npx ENOENT, fix executable discovery first using the dedicated guide. Use MCP Inspector when you need to separate a server problem from a client integration problem.

Close the loop with evidence

A useful resolution records what changed and what succeeded afterward: the server appears connected, discovery completes, and one approved read-only request returns the expected result. “The error disappeared once” is weaker evidence than a repeatable check.

Keep a redacted troubleshooting note with client and server versions, operating system, transport, config scope, exact error, timestamp, and the one change that resolved it. Remove API keys, authorization headers, cookies, private document contents and sensitive local paths before sharing a log. For Claude-specific setup, return to the Claude Code MCP hub. If the same server is being used in Cursor, use the Cursor MCP hub and its client-specific instructions instead of treating Claude’s configuration as portable.

Tips

• Treat “connection closed” as a symptom: record the last successful step before changing config.
• If the error is spawn npx ENOENT, fix executable discovery first; do not start with timeouts.
• Confirm transport and type: a URL without a type is a Claude Code configuration error.
• Change one setting at a time and rerun the same test.
• Use MCP Inspector to separate a server problem from a client integration problem.

Next steps

Sources

• https://code.claude.com/docs/en/mcp · checked 2026-11-11
• https://modelcontextprotocol.io/docs/tools/debugging · checked 2026-11-11