Appears when: MCP server failed to connect
An MCP connection failure is usually a transport, command, working-directory, environment, authentication, or protocol-startup problem. Test the server command outside Claude Code, inspect MCP status and logs, and use configuration syntax that matches the installed Claude Code version.
# Record versions and current configCapture Claude Code version, MCP server version, transport, and scope before editing.# Make the server command independently healthyResolve executable, dependency, working-directory, and credential failures first.# Re-add the server with current syntaxUse official documentation for the installed version and the intended local, project, or user scope.# Verify discovery and one read-only toolRestart or reload as required, confirm tool discovery, then test the least privileged operation.Preserve the current working revision, change one proven boundary, and verify the published path in a clean session.
Inspect the server name, command or URL, arguments, environment, and project/user scope in the installed Claude Code version.
What the result tells you: A valid server in the wrong scope can look missing in the current project.
Use the same working directory and environment without adding output to standard input/output.
What the result tells you: A missing executable, dependency, permission, or credential becomes visible before the MCP layer.
For stdio, protocol messages need a clean channel; diagnostic logs should go to standard error.
What the result tells you: Extra stdout banners or an immediate process exit can prevent the client handshake.
Verify required environment variable names, login state, and token availability.
What the result tells you: A server may start correctly and then exit when its upstream API rejects authentication.
| Likely cause | What proves it | First safe action |
|---|---|---|
| Command or executable is unavailable | A valid server in the wrong scope can look missing in the current project. | Record versions and current config |
| Server process exits during startup | A missing executable, dependency, permission, or credential becomes visible before the MCP layer. | Make the server command independently healthy |
| Transport output is contaminated | Extra stdout banners or an immediate process exit can prevent the client handshake. | Re-add the server with current syntax |
| Configuration syntax or scope changed | A server may start correctly and then exit when its upstream API rejects authentication. | Verify discovery and one read-only tool |
An MCP connection failure is usually a transport, command, working-directory, environment, authentication, or protocol-startup problem. Test the server command outside Claude Code, inspect MCP status and logs, and use configuration syntax that matches the installed Claude Code version.
Claude Code cannot resolve the configured binary from its environment.
Dependencies, permissions, working directory, or required configuration are missing.
A stdio server prints non-protocol text to stdout.
Freeze generated changes, restore the last known working version, reproduce one request, collect the browser and platform logs, and change one layer at a time.
The client can have a different working directory, PATH, environment, configuration scope, or permission context.
Avoid non-protocol output on stdout. Send diagnostics to stderr so the protocol channel stays clean.
MCP configuration commands and behavior can change. Record versions and follow the official documentation for the installed release.
Free decision aid
Get a senior view of the constraint, the evidence you have, and the next decision that removes the most risk.
No email required for this decision aid. Dismiss once and this popup stays closed for the session.