Search

Home › Learn › Add an MCP server to Codex

Add an MCP server to Codex

Updated 2026-09-23

OpenAI's Codex (the CLI, the IDE extension and the ChatGPT desktop app) stores MCP configuration in a TOML file and shares it across those clients, so a server configured once is available in all of them. The details below come from the Codex MCP documentation page as read on 2026-09-23. Note that developers.openai.com/codex/mcp currently redirects to learn.chatgpt.com/docs/extend/mcp; the openai/codex repository's docs/config.md points at the developers.openai.com configuration pages rather than documenting options inline.

What Codex supports

Where the config lives

Codex keeps MCP settings in config.toml. The default is ~/.codex/config.toml; a project can also carry .codex/config.toml, which the docs say applies to trusted projects only.

Add a server with the CLI

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

The docs' example adds Context7:

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

Everything after -- is the command that starts the server. Other commands on the page:

For a remote server with a pre-registered OAuth client the docs show:

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

Codex then prints the callback URL to register with the provider.

Edit config.toml directly

Each server is a [mcp_servers.<server-name>] table.

STDIO fields: command (required), args, env, env_vars (variable names to allow and forward from the local environment), cwd, and experimental_environment.

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

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

Streamable HTTP fields: url (required), auth (oauth by default, or chatgpt for the trusted first-party origin), bearer_token_env_var (the name of an environment variable whose value is sent in Authorization), http_headers (static header map), env_http_headers (header name to environment variable name), and http_headers_helper (a local command that prints a JSON object of headers).

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

The docs describe the precedence: explicit bearer tokens and OAuth credentials take precedence over a helper-provided Authorization header, and if no credential source resolves, Codex connects without authentication. Note the design choice behind bearer_token_env_var and env_http_headers: the file holds the name of a variable, never the token, which keeps config.toml safe to share.

Per-server controls that apply to both transports: startup_timeout_sec (default 10), tool_timeout_sec (default 60), enabled, required (fail startup if this server cannot initialize), enabled_tools (allow list), disabled_tools (deny list, applied after the allow list), default_tools_approval_mode (auto, prompt, writes or approve; writes prompts for tools not marked read-only), and per-tool tools.<tool>.approval_mode and tools.<tool>.output_token_limit.

[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

[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"
output_token_limit = 30000

The tool allow/deny lists and approval modes are the knobs to reach for when a server exposes more than you want the agent to use; see the security checklist.

OAuth details

Codex saves a configured client ID and callback in the server's [mcp_servers.<name>.oauth] table:

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

[mcp_servers.example.oauth]
client_id = "my-client"
callback_url = "http://127.0.0.1/callback"

Global overrides mcp_oauth_callback_port and mcp_oauth_callback_url exist for fixed ports and proxied callbacks. The page also documents how Codex chooses between CIMD and DCR automatically, and the --oauth-client-registration cimd|dcr flag on codex mcp login to force one for a single login. Those rules are detailed and version-specific; read the page directly before registering an OAuth app for a Codex integration.

Plugin-provided servers

Installed plugins can bundle MCP servers in their manifest; user config can only toggle them and set tool policy under plugins.<plugin>.mcp_servers.<server>. Plugin manifests use an mcpServers JSON block with camelCase OAuth keys (clientId, callbackUrl, callbackPort).

What is not covered here

The full, searchable list of every supported MCP option lives in the Codex configuration reference, which the MCP page links as https://learn.chatgpt.com/docs/config-file/config-reference and the repository's docs/config.md links as https://developers.openai.com/codex/config-reference. This article did not read that reference; for anything beyond the fields quoted above, see the official docs.

Where mcpnav fits

mcpnav's Connect block currently prints the Claude Code command and a generic mcpServers JSON snippet generated from the Registry's packages and remotes. To use one with Codex, map the JSON fields onto the [mcp_servers.<name>] table above: command/args/env for stdio, url plus a bearer_token_env_var or http_headers entry for a remote endpoint.

Sources

Sources