How to Configure MCP Servers in Codex CLI

Steps

1. 01

   Understand the config file: ~/.codex/config.toml

   All persistent Codex settings — including MCP server definitions — live in ~/.codex/config.toml. This file is created the first time you run Codex. MCP servers are declared in this file using their command and args keys. You can also override any key at invocation time with -c key=value (the value is parsed as TOML), which is useful for one-off model or server changes without touching the file. For example, to override the model for a single run:

   codex -c model="o3"

2. 02

   List all configured MCP servers

   To see every MCP server currently registered in your config, run:

   codex mcp list

3. 03

   Inspect a specific MCP server

   To view the full configuration of a single named server (transport, command, args, env keys), use mcp get with the server's name:

   codex mcp get <name>

4. 04

   Add an MCP server

   The mcp add subcommand registers a new server non-interactively. It requires a NAME and either a command (for stdio servers, passed after --) or a --url (for streamable HTTP servers). The result is written to ~/.codex/config.toml. For a stdio server, pass the name and then the command and its arguments after --: codex mcp add <name> -- <command> [args...] For a streamable HTTP server, pass the name and the URL: codex mcp add <name> --url <URL> Optional flags for add: --env KEY=VALUE (stdio only, repeatable), --bearer-token-env-var, --oauth-client-id, --oauth-resource. Example — add Context7 as a stdio server:

   codex mcp add context7 -- npx -y @upstash/context7-mcp

5. 05

   Remove an MCP server

   To deregister a server by name:

   codex mcp remove <name>

6. 06

   Authenticate and deauthenticate an MCP server (OAuth only)

   Some MCP servers use OAuth and require their own login step separate from your Codex/OpenAI auth. Both subcommands require the server's NAME. Token-based servers (such as GitHub PAT) do not use these commands — set their tokens via --env at add time or as environment variables instead. mcp login also accepts an optional --scopes flag.

   codex mcp login <name>
   codex mcp logout <name>

7. 07

   Edit ~/.codex/config.toml directly for fine-grained control

   For stdio servers, each server block uses a command string and a separate args array. There is no transport key to write — transport is derived by Codex from whether command or url is present (codex mcp get displays a derived 'transport: stdio' line, but you do not write that key yourself). Environment variables go in a nested [mcp_servers.<name>.env] sub-table. Use codex mcp add to create entries initially — it writes syntactically correct TOML. Manual edits are fine for tweaks (adjusting args, env var names), but a TOML syntax error can prevent the entry from loading; run codex doctor and validate the file if a server stops appearing. Real config.toml shape (verified from codex-cli 0.141.0 generated config, 2026-06-20):

   # ~/.codex/config.toml — real schema (command is a string, args is a separate array)
   [mcp_servers.context7]
   command = "npx"
   args = ["-y", "@upstash/context7-mcp"]
   
   # GitHub MCP is now a REMOTE server (the old npm package is deprecated) — add it from the CLI:
   #   codex mcp add github --url https://api.githubcopilot.com/mcp --bearer-token-env-var GITHUB_PAT
   # Confirm exact package names/URLs against each server's own docs

8. 08

   Run Codex as an MCP server (codex mcp-server)

   Codex CLI can act as an MCP server itself, exposing its capabilities to other tools or orchestrators over stdio. This is the codex mcp-server subcommand (note: mcp-server with a hyphen, not a space). It is particularly useful when building multi-agent pipelines where another agent needs to call Codex as a tool.

   codex mcp-server

9. 09

   Diagnose your installation with codex doctor

   If something is not working — tools not appearing, auth errors, runtime failures — run the built-in diagnostics command. It checks your install, config file, authentication status, and runtime health, and prints a summary of what is healthy and what needs attention.

   codex doctor

10. 10

    Limit the number of active servers

    Connecting every available MCP server is tempting but counterproductive. The practical guidance (widely reported by practitioners, not a formally documented hard limit): keep 2-3 servers connected at a time. Connecting more than 5-7 servers tends to fill the agent's context with tool definitions, which can degrade response quality and increase latency. Add only the servers you actively use for a given workflow, and remove or disable the rest.

    # Remove a server you are not currently using
    codex mcp remove <name>

Troubleshooting

codex: command not found after npm install

The npm global bin directory is not on your PATH. Run npm prefix -g to find the global prefix (the bin directory is that path + /bin), or run npm config get prefix. Add the bin directory to your PATH in ~/.zshrc or ~/.bashrc. For example: export PATH="$(npm prefix -g)/bin:$PATH". Alternatively, use the standalone installer which handles PATH automatically. Verify after restarting your terminal.

codex mcp list returns an empty list even though servers were added

Run codex doctor to check that the config file path is correct and readable. If you edited ~/.codex/config.toml manually, check for TOML syntax errors — a syntax error can prevent the entry from loading. Run codex doctor and validate the file. Use codex mcp add to re-add a server with the correct non-interactive syntax, which writes valid TOML.

MCP server tools are not appearing in a Codex session

First run codex mcp list to confirm the server is registered. Then run codex doctor to check runtime health. If the server uses stdio, ensure the command (e.g. npx -y @upstash/context7-mcp) is resolvable in your shell — npx may need to download the package on first run. If the server uses OAuth, run codex mcp login <name> for that server. Also consider whether you have many servers connected: practitioners report that connecting more than 5-7 servers at once can degrade agent performance (see honestyNotes for the framing of this guidance).

Authentication errors when using a GitHub or OAuth-backed MCP server

For OAuth-backed servers, run codex mcp login <name> (not codex login, which is for your OpenAI/Codex account). The mcp login subcommand handles OAuth flows specific to individual MCP servers. If you need to reset, run codex mcp logout <name> first, then codex mcp login <name> again. For token-based servers like GitHub, ensure the relevant environment variable (e.g. GITHUB_PERSONAL_ACCESS_TOKEN) is set — either pass it at add time with --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx or export it in the shell where you run Codex. Token-based servers do not use codex mcp login.

codex doctor reports config or runtime errors after a fresh install

The most common cause is a missing or malformed ~/.codex/config.toml. Delete the file (mv ~/.codex/config.toml ~/.codex/config.toml.bak) and let Codex recreate it on next launch. Then re-add your servers with codex mcp add <name> -- <command> [args...]. If doctor still reports errors, check that your Node.js version meets the requirement listed in the @openai/codex package documentation.