Add an MCP server to Codex CLI: the [mcp_servers] block in config.toml
Connecting MCP servers to Codex CLI: the [mcp_servers.<name>] block in config.toml, passing tokens through environment variables, and debugging a server that will not connect.
Contents
Connecting an MCP (Model Context Protocol) server to Codex CLI lets it drive a browser, search documentation or read issues on its own initiative. Codex keeps all of that configuration in config.toml, which means the syntax differs from Claude Code and Gemini CLI even when the underlying server is identical.
This article covers writing the config, adding servers from the command line, checking the connection, and narrowing down a server that won't start.
KEY POINT
What you will learn
- The
[mcp_servers.<name>]block for stdio servers - Passing tokens through environment variables rather than the config file
- A checking order for when a server doesn't connect
Writing it in config.toml
Add one section per server to ~/.codex/config.toml.
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "${GITHUB_TOKEN}" }
| Key | Meaning |
|---|---|
command | The command that starts the server |
args | Arguments to that command, as an array |
env | Environment variables handed to the server process |
Values in env are passed when the server starts. Keep tokens out of the file itself and read them from your shell instead.
Never put a token directly in config.toml
config.toml is exactly the kind of file that leaks through backups and shared dotfiles. Write an environment variable reference such as ${GITHUB_TOKEN} in env and keep the real value in your shell. If your version doesn't expand environment variables there, point command at a small wrapper script and read the variable inside the script.
Adding servers with codex mcp
Instead of editing TOML by hand:
codex mcp add playwright -- npx @playwright/mcp@latest
codex mcp list
codex mcp remove playwright
What the command adds is written to config.toml, so you can edit it by hand afterwards. Which subcommands exist varies by version — check codex mcp --help.
Checking the connection
Start Codex and run /mcp in the session to list the registered servers and the tools each provides. If a server is missing or errors, work through this order:
- Start the server on its own: run
npx @playwright/mcp@latestdirectly in a terminal. A failed npm download or an old Node.js shows up here. - Check the environment variable:
echo $GITHUB_TOKEN. If the shell you launched Codex from doesn't have it, the server doesn't either. - Check the TOML syntax: a missing comma in an array or an unclosed quote is the usual cause.
/statusshows whether your configuration loaded. - Sandbox network limits: the MCP server itself runs outside the Codex sandbox, but if the commands Codex runs need the network,
network_accessmatters — see Codex approval modes and sandbox.
用語解説
stdio transport: Codex starts the server as a subprocess and talks to it over standard input and output. Most locally-run MCP servers work this way. For remote (HTTP) servers, check the official documentation for your version's support.
How this compares across the three tools
| Tool | Config file | Format |
|---|---|---|
| Codex | ~/.codex/config.toml | TOML, [mcp_servers.<name>] |
| Claude Code | .mcp.json / ~/.claude.json | JSON, mcpServers |
| Gemini CLI | ~/.gemini/settings.json / .gemini/settings.json | JSON, mcpServers |
Because the values you supply — command, args, env — are the same everywhere, a server that works in one tool only needs rewriting into the other's format. For Claude Code see Adding MCP servers to Claude Code, and for Gemini CLI Adding an MCP server to Gemini CLI. For which servers to install first, see Five MCP servers worth installing first.
Summary
- Put
command,argsandenvunder[mcp_servers.<name>]in~/.codex/config.toml - Read tokens from environment variables; never write them into
config.toml - Check state with
/mcp, then debug in order: run the server alone, check the variable, check the TOML - The command, args and env values are the same across Claude Code and Gemini CLI, so configurations port over
FAQ
- Where does Codex MCP configuration go?
- In a [mcp_servers.<name>] section of ~/.codex/config.toml. The codex mcp add command writes it there for you.
- Can I reuse a Claude Code .mcp.json as-is?
- No. The format differs: Codex uses TOML, so the command, args and env values have to be rewritten. The values themselves carry over unchanged.
- Do MCP tools run without approval?
- They follow your approval policy. Under on-request, Codex asks when it judges approval is needed.
Questions & answers
Q. The desktop app's Authenticate button never saves OAuth tokens for my pre-registered MCP client, though codex mcp login works. Which is the supported path?
The documented way to perform an OAuth login is the CLI command: "For a server that supports OAuth, run codex mcp login <server-name>." The docs say nothing about a button in the desktop app. If the CLI works for you, treat it as the supported path.
Configuration is shared between the three clients — the ChatGPT desktop app, Codex CLI and the IDE extension — and lives in ~/.codex/config.toml by default. A login you complete from the CLI is therefore usable from the other clients that read the same configuration.
For a pre-registered client, pass the client ID when you add the server:
codex mcp add example --url https://mcp.example.com --oauth-client-id my-client
For a confidential client, pass the secret too, read from an environment variable:
codex mcp add example --url https://mcp.example.com \
--oauth-client-id my-client --oauth-client-secret "$MCP_CLIENT_SECRET"
The secret is stored in config.toml in plain text
The documentation is explicit: "Codex saves the secret as mcp_servers.example.oauth.client_secret in config.toml. Keep that file private and out of version control."
The client ID and callback are stored like this:
[mcp_servers.example]
url = "https://mcp.example.com"
[mcp_servers.example.oauth]
client_id = "my-client"
callback_url = "http://127.0.0.1/callback"
The default callback is http://127.0.0.1/callback. Override the port or URL with mcp_oauth_callback_port and mcp_oauth_callback_url. To pick a registration method for one login, use codex mcp login <server-name> --oauth-client-registration cimd (or dcr); the default is auto, and the choice is not stored in config.toml.
codex mcp list shows configured servers, and /mcp shows their status during a session. For adding servers in the first place, see Adding an MCP server to Codex CLI.
Q. In the Codex desktop app, "Always allow" for an MCP tool stops working in a new chat — the prompt returns. I have a per-tool approval_mode in config.toml. Can I authorize across chats?
It helps to separate what the documentation settles from what it does not.
What it settles: per-tool approval is a documented setting. default_tools_approval_mode is the server-wide default and tools.<tool>.approval_mode is the per-tool override. The docs read: "Default approval behavior for tools from this server. Supported values are auto, prompt, writes, and approve" and "Per-tool approval behavior override."
[mcp_servers.google-ads]
command = "..."
default_tools_approval_mode = "prompt"
[mcp_servers.google-ads.tools.list_accounts]
approval_mode = "approve"
What it does not settle: of those four values, the only one the documentation explains is writes — "The writes mode prompts for tools that aren't marked read-only." What auto, prompt and approve actually do is stated neither in the configuration reference nor on the MCP page.
The official example is still informative: it sets the server default to prompt and then overrides one tool with approval_mode = "approve". That arrangement reads as approve being the more permissive side, the one that does not prompt — but the documentation does not say so outright.
How long "Always allow" lasts: whether the UI's "Always allow" survives into a new chat could not be confirmed in the official documentation. Where the Codex docs do discuss a persisting "Always allow", it is for Browser Use and for Windows Computer Use app entries; there is nothing equivalent for MCP tools.
注意
So the reliable route today is config.toml rather than the UI's "Always allow". If approval_mode = "approve" still prompts every time, the setting may not be reaching the session: check that the [mcp_servers.<server>.tools.<tool>] table name matches the server id and tool name exactly. Whether this key takes effect through the desktop app's path specifically is not stated in the documentation.
A different lever worth knowing: enabled_tools is an allow list of the tool names a server exposes and disabled_tools is a deny list applied after it. Those control whether a tool is offered at all, not how it is approved.
More detail: Set up MCP servers in Codex.
Primary sources
This article was drafted by AI from official documentation and reviewed by the site operator before publishing. Found a mistake? Let us know via the contact page.