MCP server not showing in Claude Code or Codex? Find out which of three problems you have

A troubleshooting guide lays out three distinct failure modes for MCP servers that appear broken in Claude Code or Codex — a server missing from the list, a server that fails to start, or a server that needs authentication — and gives the specific commands and config locations for each. It notes that Claude Code stores servers in ~/.claude.json or a project's .mcp.json while Codex uses ~/.codex/config.toml, and that the two tools never read each other's files. Common startup failures trace to PATH differences for node, npx, uvx or docker, and can be addressed with the MCP_TIMEOUT variable in Claude Code or startup_timeout_sec in Codex.

"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 https://www.agentflowshub.com/en/learn/mcp-server-not-showing Written with AI assistance.