"The MCP server is not working" can mean three different things, and each has a different fix. Before you edit any configuration, find out which one you have:
| Claude Code | Codex | |
|---|---|---|
| List servers | claude mcp list , or/mcp in a session |
codex mcp list , or/mcp in the TUI |
| Add a local server | `claude mcp add <name> -- <command> [args]` | `codex mcp add <name> -- <command>` |
| Add a remote server | `claude mcp add --transport http <name> <url>` | `codex mcp add <name> --url <url>` |
| Stored in | ~/.claude.json (local and user scope) or.mcp.json in the project root (project scope) | ~/.codex/config.toml , or.codex/config.toml in a trusted project, under[mcp_servers.<name>] |
The desktop app, CLI and IDE extension of Codex share one configuration. Claude Code and Codex never read each other's files, so a server added to one is invisible to the other.
--scope user makes it available in every project..mcp.json waits for your approval the first time Claude Code opens that folder. Until then it shows Pending approval.
Claude Code shows Connected, Needs authentication or Failed to connect.
/mcp and sign in, or claude mcp login <name> from the terminal. In Codex, run codex mcp login <name>. node, npx, uvx or docker is the most common cause. An application started from a desktop shortcut may not see the same PATH as your terminal.MCP_TIMEOUT environment variable in milliseconds (MCP_TIMEOUT=10000 claude). Codex uses startup_timeout_sec in the server's entry; the default is 10 seconds.
A local server that fails to start is not retried automatically in Claude Code. After you fix it, choose Reconnect in /mcp. Change one thing at a time and look at the status again after each change.
The application and version, the scope or config file, the server name, how it connects (local command or URL), the status shown and the exact error message. Remove tokens and private data first.
The same checklist, with more detail on each state: MCP server not showing in Claude Code or Codex Written with AI assistance.