Claude Code MCP Failed to Connect: Config, OAuth & Stdio

Paste your error / 粘贴报错原文

Paste an error to match it against the wiki. / 粘贴报错后自动匹配。

Error text / 报错原文

MCP servers failed to connect
Invalid MCP configuration
SSE stream disconnected
TypeError: terminated

Locate the failing stage

Symptom	Stage	First action
`Invalid MCP configuration` or unresolved `${VAR}`	Configuration	Validate the JSON and required environment variables
Project server is disabled or awaiting trust	Scope approval	Open `/mcp` and approve the project-scoped server
`ENOENT`, process exit, or no initialize response	Local stdio startup	Run the exact command from Claude Code's launch directory
Connection refused, timeout, terminated, or SSE disconnect	HTTP/SSE transport	Check the endpoint, proxy, TLS, and server logs
`401`, `403`, or token expired	Remote OAuth	Open `/mcp` and complete authentication
Connected but reports zero tools	Tool discovery	Inspect the server's tool list and protocol response

Fastest diagnostic sequence

Run claude mcp list to identify the failing server and connection type.
Run claude mcp get <name> to inspect its effective command, URL, scope, and environment.
Inside Claude Code, open /mcp for connection status, OAuth, project approval, and tool count.
Restart with claude --debug mcp when the summary is not enough.
For a local stdio server, execute the exact command manually from the directory where Claude Code was launched.

Configuration and scope checks

Claude Code supports local, project, user, plugin, and Claude.ai MCP sources. A higher-precedence source can shadow a same-named lower source.
Project-scoped servers require explicit approval before use.
Environment expansion supports ${VAR} and ${VAR:-default}. A missing required variable can invalidate startup.
Relative values in command and args resolve from the directory where Claude Code was launched, not from the directory containing .mcp.json.
workspace is a reserved server name. Rename the server if that name appears in the configuration.

Paste the JSON into the MCP Config Doctor to catch syntax, schema, client-format, reserved-name, and environment-placeholder problems locally in the browser.

Local stdio vs remote HTTP/SSE

Local stdio server

Claude Code launches a child process and communicates over standard input/output. It does not automatically reconnect a stdio server after the process exits, so fix the command, runtime, permissions, working directory, or missing environment value and restart it.

Remote HTTP or SSE server

Current Claude Code documentation says remote servers automatically reconnect up to five times after a mid-session disconnect. Initial connections retry up to three times in current releases. Repeated failure therefore points to the endpoint, network, proxy, TLS, server availability, or authentication—not simply a missing retry button.

OAuth and “connected, 0 tools”

For 401 or 403, open /mcp, choose the server, and complete the OAuth flow.
If the browser succeeds but Claude Code stays unauthorized, disconnect and reconnect that MCP server rather than logging the whole Claude account out.
If status says connected but tool count is zero, transport and auth likely succeeded. Inspect the server's tools/list support, permissions, and server logs.
Do not confuse a disabled project server with a broken transport; approval happens before connection.

What not to do

Do not hardcode access tokens in a checked-in .mcp.json; use environment placeholders.
Do not run untrusted project-scoped servers before reviewing their command and permissions.
Do not enable every server globally. More tools increase startup work and context usage.
Do not debug a stdio process as if it were an HTTP server; their failure and reconnect behavior differ.

How to confirm the fix

Use /mcp to confirm the server is connected and exposes the expected non-zero tool count. Then invoke one harmless read-only tool before retrying the original agent task.

claude mcp list
claude mcp get <name>
claude --debug mcp
claude doctor

Related errors

FAQ

Why does the MCP command work in my shell but fail in Claude Code?

The launch directory, PATH, environment variables, or runtime may differ. Check the effective configuration with claude mcp get <name> and use absolute executable paths when appropriate.

Does Claude Code reconnect MCP servers automatically?

Remote HTTP/SSE servers have automatic retries; local stdio servers do not reconnect after exiting.

What does connected with zero tools mean?

The connection probably passed configuration, transport, and authentication, but tool discovery returned nothing or the account lacks permission to see tools.

Claude Code MCP server failed to connect