CODEX · MCP

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

Run codex mcp add <name> -- <command> for a local server, or codex mcp add <name> --url <address> for a remote one; both write an [mcp_servers.<name>] table to ~/.codex/config.toml. The Codex CLI, the IDE extension and the ChatGPT desktop app all read that file.

Start freeGet started Explore the team demo

Free for 3 seats · No credit cardStarter covers 3 seats · Pro is $49 a month for 5 · The demo needs no signup

Open the live team demo

Sample data, no signup · Create a free accountCreate your account

Zest lemon in its mech suit

02Share the best AI skills

Weekly email

Your team’s weekly edge

Zestto your teamEvery Monday

AI stack worth sharing

  • Agree on the approach before coding.

    The brainstorming skill helps the team make a plan together.

    - [ ] **Plan** before coding.12 → 21 sessions · 5 → 8 teammates
  • Let agents work safely in parallel.

    using-git-worktrees gives each agent its own space to work.

    - [ ] One agent, one `worktree`.4 sessions · 2 → 3 teammates
  • Catch missing requirements early.

    A quick gap analysis finds what’s missing before anyone starts building.

    - [ ] **Find** missing cases.38 of 134 sessions · 9 teammates

USED BY ENGINEERING TEAMS AT

Flyps Charm Wildfires Geoforge MisaLabs

How to add an MCP server to Codex

codex mcp add edits ~/.codex/config.toml for you. A local server's start command goes after --; a remote server gets its address with --url instead, and the two forms can't be mixed.

--env KEY=VALUE sets a variable for a local server and can be repeated. For a remote server, --bearer-token-env-var names the environment variable Codex reads the token from, so the file holds the variable's name and never the token.

# a local (stdio) server: everything after -- starts it
codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <stdio server-command>

# a remote (streamable HTTP) server
codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp
codex mcp add figma --url https://mcp.figma.com/mcp --bearer-token-env-var FIGMA_OAUTH_TOKEN

How to list, check and remove Codex MCP servers

In a running session, /mcp shows the MCP tools Codex can call right now. When a server you added is missing from that list, /mcp verbose prints each server's diagnostics. From a shell:

  • codex mcp list: every configured server. Add --json for a script.
  • codex mcp get <name>: one server's settings, or its raw entry with --json.
  • codex mcp remove <name>: deletes the server's definition.
  • codex mcp login <name> and codex mcp logout <name>: sign in to a remote server that uses OAuth, or drop its stored credentials.
Inside the Codex CLI
/mcp                # MCP tools this session can call
/mcp verbose        # plus each server's diagnostics
/mcp login <name>   # sign in to a configured server mid-session

Codex MCP config in config.toml

Each server is one [mcp_servers.<name>] table. By default Codex reads ~/.codex/config.toml, plus any .codex/config.toml inside a project you have marked as trusted; in an untrusted project it ignores the project file.

A local server needs command. args, env (values you set for it), env_vars (variables passed through from your own environment) and cwd are optional. A remote server needs url, and takes credentials from bearer_token_env_var, from fixed http_headers, from env_http_headers filled in from your environment, or from http_headers_helper, a local command that prints the headers as JSON.

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

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

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

Codex MCP timeouts, tool lists and approvals

Codex gives a server 10 seconds to start and each tool call 60 seconds. Raise startup_timeout_sec for a server that boots slowly, and tool_timeout_sec for tools that run long.

enabled_tools keeps only the tools you name, and disabled_tools removes tools after that. default_tools_approval_mode sets when Codex asks before calling a server's tools: prompt asks every time, and writes asks only for tools not marked read-only. A tools.<tool> table overrides the mode for one tool and can cap that tool's output with output_token_limit.

enabled = false switches a server off and keeps its settings. For a single run, codex -c mcp_servers.<name>.enabled=false does the same from the command line.

~/.codex/config.toml
[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

How to log in to an MCP server with OAuth

For a remote server that supports OAuth, codex mcp login <name> opens the sign-in in your browser. On a machine with no browser, add --no-browser, open the printed URL on another device and paste the full redirect URL back into the terminal, even when the page it lands on fails to load.

--scopes read,write picks the scopes for one login, and a scopes list in the server's table picks them every time. With neither, Codex asks for the scopes the server names in its first authentication challenge.

Some authorization servers want a client registered ahead of time. Pass --oauth-client-id when you add the server, add --oauth-client-secret for a confidential client (Codex CLI 0.158.0 and later), and register the exact callback URL codex mcp add prints. Codex stores that secret in config.toml as oauth.client_secret, which is a reason to keep the file out of version control.

codex mcp login <server-name>
codex mcp login <server-name> --no-browser
codex mcp login <server-name> --scopes read,write
codex mcp add example --url https://mcp.example.com --oauth-client-id my-client --oauth-client-secret "$MCP_CLIENT_SECRET"

MCP in the Codex IDE extension and the ChatGPT desktop app

The CLI, the IDE extension and the ChatGPT desktop app share one config.toml, so a server added in any of them shows up in the other two. In the IDE extension it's the gear menu, then MCP servers and Add server, then Restart extension once you save. In the desktop app the same list sits under Settings > MCP servers, followed by Restart.

ChatGPT on the web is the exception. It doesn't read local Codex configuration at all, and reaches remote MCP tools only through installed plugins.

A server that ships inside a Codex plugin is launched by the plugin, so your config can't change its command. It can still switch the server off or set its tool rules under plugins."<plugin>".mcp_servers.<server>.

~/.codex/config.toml
[plugins."sample@test".mcp_servers.sample]
enabled = true
default_tools_approval_mode = "prompt"
enabled_tools = ["read", "search"]

Can Codex run as an MCP server?

Not any more. codex mcp-server, which let another agent call Codex as an MCP tool, printed a deprecation warning from Codex CLI 0.149.0 (August 20, 2026) and was removed in 0.154.0 (September 9, 2026), together with the standalone codex-mcp-server binary. OpenAI's docs say any integration that launches either one has to migrate before it upgrades Codex.

The replacement is the Codex app server, codex app-server. It talks its own JSON-RPC protocol rather than MCP, so the client side changes too, and OpenAI labels it experimental and not supported for production workloads. For jobs and CI, OpenAI points to the Codex SDK instead. To call Codex from Claude Code, OpenAI's Codex plugin for Claude Code already wraps the app server.

Codex as an MCP client is untouched: codex mcp and everything above work as before.

codex app-server                                  # stdio, newline-delimited JSON-RPC
codex app-server --listen ws://127.0.0.1:4500     # WebSocket, experimental
codex app-server generate-json-schema --out ./schemas

Codex MCP gotchas

From OpenAI's docs and its issue tracker:

  • Every enabled server adds context to your messages and draws down your Codex usage limits faster. OpenAI's advice is to switch off the servers you aren't using.
  • A project's .codex/config.toml loads only once the project is trusted. When a teammate's shared server doesn't appear for you, check that first.
  • Codex waits one second for optional servers before it builds the first tool list (mcp_optional_startup_grace_ms, default 1000). Set it to 0 to wait out each server's startup timeout, or mark a server required = true so the session refuses to start without it.
  • A server that came with a plugin appears in codex mcp list, yet codex mcp remove says no such server exists (openai/codex#20970, open since May 2026). Switch it off in the plugin's table instead.
  • Codex can pick up plugins from Claude Code marketplaces on your machine and try to start their MCP servers. One written only for Claude Code, whose .mcp.json uses ${CLAUDE_PLUGIN_ROOT}, fails the handshake because Codex doesn't fill in that variable (openai/codex#19372, open since April 2026).

Which MCP tools a Codex team actually calls

/mcp tells one engineer what a session could call. Zest's Codex plugin is itself a plugin-provided MCP server, a local stdio process with tools such as login, status and sync. Once you log in, it reads the session files Codex writes under ~/.codex and counts the MCP tool calls in each session's main thread by server and tool. Those counts show in each session's AI stack beside its model and skills, rolled up per engineer and tied to the pull requests the sessions led to (setup, more in Codex usage).

Hold that list against your config.toml: a server that never shows up in the counts still costs context on every message. What Zest can't show: servers that are configured but never called, because it counts calls rather than reading your config; MCP calls made inside subagent threads, which the plugin skips; and MCP tools used from ChatGPT on the web, which leave no session file on the engineer's machine.

TRY IT ON YOUR TEAM

See what your team ships with AI.

Starter is free (3 seats, no credit card). Pro is $49 a month with 5 seats and Max is $149 a month with 10 seats — priced per workspace, not per engineer, with extra seats at $19 a month. See pricing

A FEW THINGS TO KNOW

Questions

Where is the Codex MCP config file?+

In ~/.codex/config.toml, with one [mcp_servers.<name>] table per server. A trusted project can add its own in .codex/config.toml. The Codex CLI, IDE extension and ChatGPT desktop app all read the same file.

Can I still run codex mcp-server?+

No. It was deprecated in Codex CLI 0.149.0 and removed in 0.154.0, released September 9, 2026. OpenAI's replacement is the experimental codex app-server, which uses its own JSON-RPC protocol instead of MCP.

Why doesn't Codex see my MCP server?+

Run codex mcp list to check it's configured and enabled, then /mcp verbose in a session for its diagnostics. A server in .codex/config.toml loads only in a trusted project, and one that needs more than 10 seconds to start needs a higher startup_timeout_sec.

Do my Codex MCP servers work in ChatGPT on the web?+

No. ChatGPT on the web doesn't read local Codex configuration. It reaches remote MCP tools only through plugins you install there.

How do I turn off an MCP server in Codex without deleting it?+

Set enabled = false in its [mcp_servers.<name>] table, or pass -c mcp_servers.<name>.enabled=false for one run. For a server that came with a plugin, set enabled = false under plugins."<plugin>".mcp_servers.<server>.