Codex MCP: add servers with codex mcp add and config.toml

To use MCP in Codex, run codex mcp add <name> -- <command> for a local server or codex mcp add <name> --url <url> for a remote one. Codex saves the server as an [mcp_servers.<name>] table in ~/.codex/config.toml, and the CLI, IDE extension and desktop app all use it.

MCP, the Model Context Protocol, lets Codex call tools that live outside your repo: documentation search, a browser, an issue tracker, your design files. This guide covers the commands, the config keys and OAuth sign-in, based on OpenAI's Codex MCP docs and the configuration reference, read on 24 October 2026.

What MCP servers can Codex connect to?

Codex supports two transports:

Codex also reads the instructions field a server returns when it starts and uses it as guidance for that server's tools.

OpenAI's docs list example servers including the OpenAI Docs MCP, Context7 for current library docs, Figma, Playwright, Chrome DevTools, Sentry and GitHub. For a wider list with setup notes, see the best MCP servers.

How do you add an MCP server with codex mcp add?

For a local STDIO server, put the launch command after --:

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

# example from the docs
codex mcp add context7 -- npx -y @upstash/context7-mcp

--env KEY=VALUE sets an environment variable for the server and can repeat. For a remote server, use --url instead of a command:

codex mcp add figma --url https://mcp.figma.com/mcp

The main flags codex mcp add accepts in the current CLI:

• --env KEY=VALUE: environment variables for STDIO servers only.
• --url <URL>: the address of a Streamable HTTP server.
• --bearer-token-env-var <ENV_VAR>: an environment variable holding a bearer token, for HTTP servers only.
• --oauth-client-id <id> and --oauth-client-secret <secret>: a pre-registered OAuth client. The docs warn that Codex saves the secret in config.toml, so read it from an environment variable such as "$MCP_CLIENT_SECRET" and keep the file private.

What other codex mcp commands are there?

The codex mcp command group in the openai/codex source has six subcommands:

Run codex mcp --help to confirm what your installed version supports. Inside a session, /mcp lists the MCP tools Codex can call, /mcp verbose adds server diagnostics, and /mcp login <name> signs in without leaving the session.

How do you configure MCP servers in config.toml?

codex mcp add is a shortcut for writing a table by hand. You can edit ~/.codex/config.toml directly, and a trusted project can define servers in .codex/config.toml. The Codex config guide explains how those layers combine.

# local STDIO server
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["LOCAL_TOKEN"]          # forward this variable from your shell

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

# remote server with a bearer token
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

# remote server with tool filters and timeouts
[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

STDIO keys

• command (required): the command that starts the server.
• args: arguments for that command.
• env: variables to set for the server.
• env_vars: variables to forward from your local environment.
• cwd: the folder to start the server in.

Streamable HTTP keys

• url (required): the server address.
• bearer_token_env_var: the variable that holds a token for the Authorization header.
• http_headers: static headers sent with each request.
• env_http_headers: headers filled from environment variables.

Keys for both

You can also override one tool with a [mcp_servers.<name>.tools.<tool>] table that sets approval_mode or output_token_limit. To turn a server off for a single run, use a config override: codex -c mcp_servers.context7.enabled=false.

How does OAuth login work for Codex MCP servers?

Many hosted servers use OAuth instead of a token in an environment variable. Add the server with --url, then sign in:

codex mcp add linear --url https://mcp.linear.app/mcp
codex mcp login linear

Codex opens your browser and waits for the callback. Useful login options from the docs and CLI help:

• --scopes read,write overrides the scopes for one login. Otherwise Codex uses scopes from the server's config, then the scopes the server advertises.
• --oauth-client-registration auto|cimd|dcr picks how Codex registers itself for this login only. The default is auto: Codex uses CIMD when the server supports it and the callback is a supported loopback URL, and falls back to dynamic client registration (DCR) when available.
• --no-browser prints the authorization URL and accepts the callback URL without opening a browser, which helps on a remote machine.

A few config keys control the callback:

mcp_oauth_callback_port = 5555      # fixed local port for all servers
mcp_oauth_credentials_store = "auto" # auto, file or keyring

[mcp_servers.linear.oauth]
callback_port = 5556                # per-server override

If neither port is set, Codex uses a port chosen by the operating system. Set a fixed port when your OAuth provider requires you to register an exact redirect URL. If the provider gave you a client ID, set mcp_servers.<name>.oauth.client_id so Codex skips client registration.

Do MCP servers work in the Codex IDE extension?

Yes. OpenAI's docs say the desktop app, CLI and IDE extension share the same MCP configuration, so a server you add in one shows up in the others. In the IDE extension:

1. Open the gear menu and select MCP servers.
2. Select Add server.
3. Enter a name, choose STDIO or Streamable HTTP, and enter the command or URL.
4. Save, then select Restart extension.

ChatGPT on the web is different: it does not read local Codex config files and gets remote MCP tools through plugins instead. Plugins can also bundle MCP servers for the local apps, and your user config can still switch those servers on or off and set their tool policy.

Tips for using MCP with Codex

• Start with one or two servers. Every server adds tools to the list the model chooses from. Use enabled_tools to keep only what you need.
• Keep secrets out of the file. Prefer bearer_token_env_var, env_vars and env_http_headers over pasting tokens into config.toml.
• Ask before writes. default_tools_approval_mode = "writes" prompts for tools not marked read-only, a sensible middle ground for servers that can change data.
• Debug with verbose output. If a server is missing, run /mcp verbose, then raise startup_timeout_sec for slow starters such as servers launched with npx.

MCP servers give Codex access to tools; skills tell it how to use them for a specific job. The skills vs MCP guide explains when you need which, and the Claude Code MCP guide covers the same setup in Claude Code.

Where do the skills that use your servers live?

Server config is per machine, but the steps you want Codex to follow with those servers are worth saving once. Kipt keeps your prompts and Agent Skills as Markdown in a private GitHub repo you own and installs every skill into Codex or Claude Code with npx skills add https://github.com/<you>/<repo>.git --all -g. If a prompt like "triage this Sentry issue" works well, the free SKILL.md generator turns it into a skill.