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

"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:

1. The server is missing from your application's list.
2. The server is listed but not connected.
3. The server is connected, but the tool you wanted never runs.

First, see what is configured

	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.

1. The server is missing

• Check that you added it to the application you are actually using.
• In Claude Code, check the scope. A local-scope server loads only in the project folder where you added it; --scope user makes it available in every project.
• A server in a project's .mcp.json waits for your approval the first time Claude Code opens that folder. Until then it shows Pending approval.
• If the same name is defined in more than one place, Claude Code uses one definition: local scope first, then project, user, plugin-provided servers and claude.ai connectors. Fields are not merged, so editing a lower-priority copy has no effect.

2. The server is listed but not connected

Claude Code shows Connected, Needs authentication or Failed to connect.

• Needs authentication: run /mcp and sign in, or claude mcp login <name> from the terminal. In Codex, run codex mcp login <name>.
• Failed, local server: run the exact command from the configuration in a terminal. A missing 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.
• Failed, remote server: check the URL against the server's documentation. A service's homepage is not its MCP endpoint.
• Slow to start: Claude Code reads the 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.

3. Connected, but the tool never runs

• Open /mcp and look at the tools the server actually exposes. Compare them with its documentation: your account may lack access to some operations, or the server may need a setting that enables them.
• Then ask for the operation by name with a small, known input, for example "use the GitHub server to list three open issues in this repository", and watch the tool activity. A plausible answer does not prove the tool ran; the model may have answered from memory.

What to include when you ask for help

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.