OpenAI Codex CLI MCP Setup: codex mcp add and config.toml Examples (2026)

OpenAI Codex stores MCP servers in TOML, not JSON. Each server is a [mcp_servers.<name>] table in ~/.codex/config.toml, or in .codex/config.toml inside a trusted project. The quickest way to add one is codex mcp add <name> -- <command>, then /mcp in the Codex terminal UI to see it running.

OpenAI's docs say the ChatGPT desktop app, Codex CLI and the Codex IDE extension "share this configuration," so a server set up once works in all three. This guide covers the command, the TOML options and the approval settings worth turning on.

Checked against: OpenAI's Codex MCP documentation on 2 November 2026. eSEOspace did not run Codex for this guide.

Add a server with the CLI

The syntax from OpenAI's docs:

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

OpenAI's example adds Context7, a free documentation server:

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

Other commands:

• codex mcp list shows configured servers.
• codex mcp --help lists every MCP command.
• codex mcp login <server-name> signs in to an OAuth server. Add --no-browser on a machine without a browser, then paste the full redirect URL back into the terminal.
• In the codex terminal UI, /mcp shows active servers.

Configure with config.toml

For more control, edit the file directly. A stdio server from OpenAI's examples:

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

[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"

env sets variables for the server. env_vars forwards variables that already exist in your environment, which keeps secrets out of the file.

A remote server with a token read from the environment:

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }

Both blocks were checked against OpenAI's docs on 2 November 2026. Note the TOML rules: strings in double quotes, arrays in square brackets, and sub-tables such as .env on their own header line.

Stdio options

Streamable HTTP options

Control tools and approvals

These options apply to any server:

• enabled_tools: an allow list of tools.
• disabled_tools: a deny list, applied after enabled_tools.
• default_tools_approval_mode: auto, prompt, writes or approve. OpenAI says writes "prompts for tools that aren't marked read-only."
• tools.<tool>.approval_mode: override approval for one tool.
• startup_timeout_sec (default 10) and tool_timeout_sec (default 60).
• enabled = false disables a server without deleting it; required = true makes startup fail if the server is not ready.

OpenAI's example combines several:

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"] # applied after enabled_tools
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45
enabled = true

A good starting policy for business data is default_tools_approval_mode = "writes", so read-only tools run and anything that changes data asks first. Our tool permission planner helps you decide which tools belong in each list.

OAuth sign-in

Codex supports OAuth with Client ID Metadata Documents (CIMD) and Dynamic Client Registration (DCR). By default it picks CIMD when the authorization server advertises support, and DCR otherwise. For a server that needs a pre-registered app:

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

Add --oauth-client-secret "$MCP_CLIENT_SECRET" for a confidential client. OpenAI warns that Codex saves the secret in config.toml, so "keep that file private and out of version control." Register the exact callback URL that codex mcp add prints. Our MCP authentication guide explains CIMD and DCR.

Servers that come with plugins

Installed Codex plugins can bundle their own MCP servers. OpenAI's docs say you cannot change how those servers start, but you can still control them under plugins.<plugin>.mcp_servers.<server>:

[plugins."sample@test".mcp_servers.sample]
enabled = true
default_tools_approval_mode = "prompt"
enabled_tools = ["read", "search"]

This is worth doing for any plugin you install, since it applies the same tool allowlist and approval rules as servers you added yourself.

Server instructions

If you build servers, OpenAI says Codex reads the MCP instructions field from initialization. It advises keeping "the first 512 characters self-contained," since that is what Codex sees when deciding how to use the server.

Common mistakes

• Pasting JSON into config.toml. Codex needs TOML tables, not an mcpServers object.
• Project config in an untrusted folder. .codex/config.toml only loads in trusted projects.
• Committing a client secret. codex mcp add --oauth-client-secret writes it to the file.
• Slow servers timing out. Raise startup_timeout_sec above the 10-second default.

Next step

Compare Codex with Anthropic's tool in Claude Code vs Codex for MCP, and see OpenAI and MCP for how ChatGPT plugins relate. If you want to use servers in ChatGPT on the web instead, OpenAI's custom MCP server guide covers that flow, and our ChatGPT custom MCP guide summarizes it. To test a server before adding it, use the MCP Inspector.

Frequently asked questions