Add an MCP server to Codex CLI: the [mcp_servers] block in config.toml

Codex Published:

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.

Verified on Sep 7, 2026 These tools change quickly. Please also check the latest official documentation. How articles are researched and verified
Contents
  1. Writing it in config.toml
  2. Adding servers with codex mcp
  3. Checking the connection
  4. How this compares across the three tools
  5. Summary

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}" }
KeyMeaning
commandThe command that starts the server
argsArguments to that command, as an array
envEnvironment 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:

  1. Start the server on its own: run npx @playwright/mcp@latest directly in a terminal. A failed npm download or an old Node.js shows up here.
  2. Check the environment variable: echo $GITHUB_TOKEN. If the shell you launched Codex from doesn't have it, the server doesn't either.
  3. Check the TOML syntax: a missing comma in an array or an unclosed quote is the usual cause. /status shows whether your configuration loaded.
  4. Sandbox network limits: the MCP server itself runs outside the Codex sandbox, but if the commands Codex runs need the network, network_access matters — 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

ToolConfig fileFormat
Codex~/.codex/config.tomlTOML, [mcp_servers.<name>]
Claude Code.mcp.json / ~/.claude.jsonJSON, mcpServers
Gemini CLI~/.gemini/settings.json / .gemini/settings.jsonJSON, 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, args and env under [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?

Answer by the editorsSource: GitHub openai/codex Issue #56002

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?

Answer by the editorsSource: GitHub openai/codex Issue #52963

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.