Fix MCP Server Connection Failed

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=mcp

codex mcp list --json
codex mcp get <name> --json

codex 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> --json

Decision: 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.

1. Confirm the executable exists and its package is installed.
2. Use absolute paths for local scripts; relative paths can resolve from the launch directory.
3. 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.

1. For Claude Code, put project MCP configuration in `.mcp.json` at the repository root and approve it through `/mcp`.
2. Set required per-server `env` values in the server entry; do not assume editor or settings variables reach a stdio child process.
3. 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.

1. For remote HTTP, verify URL, DNS, TLS, proxy, and service availability.
2. For OAuth, complete the browser or device flow for the exact configured server.
3. For stdio, inspect the child process and logs; it does not become healthy through remote OAuth.

codex mcp login <name>
codex mcp get <name> --json

Decision: 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.