How to add an MCP server to Codex CLI

To add an MCP server to Codex CLI, run codex mcp add <name> -- <command>, for example codex mcp add context7 -- npx -y @upstash/context7-mcp. Codex saves it as a [mcp_servers.<name>] table in ~/.codex/config.toml, and you can write those tables by hand too. A remote server takes a url, and one with OAuth signs in with codex mcp login <name>.

We took the commands and keys below from OpenAI's MCP page for Codex, first read on 23 October 2026 and checked again on 25 October 2026. codex mcp --help lists every subcommand your installed version has.

Add a local server with codex mcp add#

A local (stdio) server is a program Codex starts on your computer. Everything after -- is the command that starts it. OpenAI's full form, with environment variables passed through --env:

codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <stdio server-command>

Context7, a free server for developer documentation, is OpenAI's own example:

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

codex mcp list prints what is configured. Inside a Codex session, /mcp shows the servers that are running.

Add a remote server#

A remote server speaks Streamable HTTP at an address. If its authorization server wants a pre-registered OAuth client, give the client ID when you add it:

codex mcp add example --url https://mcp.example.com --oauth-client-id my-client

For a confidential client, add --oauth-client-secret "$MCP_CLIENT_SECRET", read from an environment variable. Codex stores that secret in config.toml as mcp_servers.example.oauth.client_secret, so keep the file out of git. It also prints the callback to register with your provider, http://127.0.0.1/callback by default; register exactly the one it shows.

Then sign in once:

codex mcp login example

--scopes read,write asks for specific scopes on that login, and a scopes key in the server's table sets them for good. With neither, Codex uses the scopes the server advertises.

The same thing in config.toml#

codex mcp add writes a table you can edit yourself. One per server:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.example]
url = "https://mcp.example.com"
bearer_token_env_var = "EXAMPLE_TOKEN"

The keys OpenAI documents:

bearer_token_env_var holds the name of an environment variable, not the token, so the token never lands in a file you might commit. env_http_headers does the same for other headers. enabled = false turns a server off without deleting it, and required = true makes Codex fail at startup if that server can't initialise.

A project can carry its own servers in .codex/config.toml, which Codex reads only when you trust the project. Which file wins when both define a key is in our config.toml guide.

Keep the tool list short#

Codex offers every server's tools to the model. enabled_tools is an allow list and disabled_tools a deny list applied after it, so enabled_tools = ["open", "screenshot"] with disabled_tools = ["screenshot"] leaves only open. Claude Code has the same problem, and too many MCP servers measures what a long tool list costs in context.

Each server can also say when its tools need your approval. default_tools_approval_mode takes auto, prompt, writes or approve; writes prompts for any tool not marked read-only. A [mcp_servers.<name>.tools.<tool>] table overrides it for one tool with approval_mode.

When a server won't start#

1. It times out at startup. A first npx run can take longer than the timeout while it downloads the package. Raise startup_timeout_sec. The error message prints the limit in force, which in current Codex releases is longer than the 10 seconds OpenAI's page lists.
2. Codex starts without it. For servers that aren't required, Codex waits mcp_optional_startup_grace_ms (1000 milliseconds by default) while it builds the first tool list. Set it to 0 to wait for each server's full startup_timeout_sec.
3. A tool call times out. Raise tool_timeout_sec, for example for a long database query.
4. It fails to start or fails the handshake. Codex MCP server failed to start goes through each error message and its fix.

One list for Codex and Claude Code#

OpenAI says the CLI, the IDE extension and the ChatGPT desktop app share this config, so a server added with codex mcp add also shows under Settings › MCP servers in the desktop app. Claude Code doesn't read it: its list lives in ~/.claude.json and .mcp.json, so a server you add here has to be added there too, sign-in and all. The Claude side is in MCP servers across all projects.

Shuriken keeps one list of MCP servers, in Settings › Extensions › MCP servers, and hands it to every Codex and Claude Code chat in the projects you choose, when the chat starts. You sign in to a server once; the sign-in belongs to the server, not to your AI account, so switching accounts or projects doesn't ask again. A server already in your Codex config.toml appears in each project's MCP servers list marked All projects. Turning it off there writes enabled = false into that file, because Codex has no per-project switch for its own servers, so the change reaches every Codex chat in every project. For a starting list, we picked MCP servers worth adding.