MCP troubleshooting
Fix MCP Server Connection Failed
Key facts
| Scope | MCP |
|---|---|
| Last verified | |
| Decision | Inspect the server from the client before editing config. In Claude Code, run `/mcp`; in Codex, run `codex mcp list --json` and `codex mcp get <name> --json`. Then test the server command independently, replace relative script paths with absolute paths, provide required environment variables in the server entry, and reconnect. |
| Official documentation | Anthropic: Debug your Claude Code configuration |
Fix MCP servers that fail to start, connect with zero tools, miss environment variables, require approval, or cannot reach a remote endpoint.
Inspect the server from the client before editing config. In Claude Code, run `/mcp`; in Codex, run `codex mcp list --json` and `codex mcp get <name> --json`. Then test the server command independently, replace relative script paths with absolute paths, provide required environment variables in the server entry, and reconnect.
Match the symptom
- The MCP server is listed as failed or disconnected.
- The server connects but exposes zero tools.
- A project server never appears or remains unapproved.
- The same configuration works from one launch directory but fails from another.
- A remote server fails OAuth, TLS, DNS, or proxy checks.
First checks
Collect evidence before changing configuration
/mcp
# If it starts with zero tools:
claude --debug=mcpcodex mcp list --json
codex mcp get <name> --jsoncodex mcp login <name>Diagnosis 1
Read the client's resolved server state
Confirm the server name, transport, command or URL, approval state, and visible tool count before modifying files.
# Claude Code session
/mcp
# Codex terminal
codex mcp list --json
codex mcp get <name> --jsonDecision: Not listed means discovery or config scope is wrong. Failed means startup or transport. Connected with zero tools means the server started but tool discovery failed.
Diagnosis 2
Test the server outside the AI client
For a stdio server, run the configured executable from the same directory and environment used to launch the client.
- Confirm the executable exists and its package is installed.
- Use absolute paths for local scripts; relative paths can resolve from the launch directory.
- Check stderr for missing modules, permissions, invalid arguments, or an early process exit.
Decision: The server must remain running and speak the expected transport before client-side retries can help.
Diagnosis 3
Verify scope, approval, and environment variables
Project configuration, user configuration, and child-process environments are separate layers.
- For Claude Code, put project MCP configuration in `.mcp.json` at the repository root and approve it through `/mcp`.
- Set required per-server `env` values in the server entry; do not assume editor or settings variables reach a stdio child process.
- Keep secrets out of committed project configuration.
Decision: Reconnect after changing configuration. If the server appears but still has zero tools, collect its debug stderr.
Diagnosis 4
Separate transport from authentication
Remote HTTP errors, OAuth failures, and local stdio exits need different fixes.
- For remote HTTP, verify URL, DNS, TLS, proxy, and service availability.
- For OAuth, complete the browser or device flow for the exact configured server.
- For stdio, inspect the child process and logs; it does not become healthy through remote OAuth.
codex mcp login <name>
codex mcp get <name> --jsonDecision: Verify success by checking both connected status and a non-zero expected tool list, then exercise one read-only tool.
If it still fails, send this evidence
A useful support request is reproducible and does not expose credentials.
- Client name and version, MCP server name, transport, and config scope.
- Resolved config with tokens, API keys, cookies, private URLs, and personal paths redacted.
- Server stderr or `claude --debug=mcp` output around the first failure.
- Output from the client list/get command and whether the server exposes any tools.
Related paths
Fix the adjacent layer without starting over.
Related account failures
Official sources
Commands and product behavior were checked against first-party documentation on August 13, 2026. Interfaces and authentication flows change; recheck the source when applying this across a team.