How to Add MCP Servers to OpenAI Codex CLI
On this page
Why Codex looks different
Most MCP guides show a JSON block with mcpServers. Paste that into Codex and nothing happens, because Codex CLI uses a TOML file and its own table names. The good news is that you rarely need to write the file yourself. The codex mcp add command writes it for you, and it's worth knowing what it produces so you can edit it later.
Everything below was run against Codex CLI 0.167.0 in November 2026.
Add a local server
For a server that runs on your machine, put the launch command after --:
codex mcp add playwright -- npx -y @playwright/mcp@0.0.84The -- separates Codex's own options from the server's command, so flags like -y go to npx and not to Codex. To pass an environment variable to the server, use --env before the --:
codex mcp add context7 --env CONTEXT7_API_KEY=your-key -- npx -y @upstash/context7-mcp@4.5.1Add a remote server
For a server you reach by URL, use --url instead of a command:
codex mcp add figma --url https://mcp.figma.com/mcpIf the server supports OAuth, Codex starts the sign-in flow straight away and waits for you to finish it in the browser. You can also run it later with codex mcp login figma, and clear the stored login with codex mcp logout figma.
For servers that use a token instead of OAuth, tell Codex which environment variable holds it. Codex reads the variable at runtime and sends it as a bearer token, so the token never lands in the config file:
codex mcp add github --url https://api.githubcopilot.com/mcp/ --bearer-token-env-var GITHUB_PATWhat ends up in config.toml
After the commands above, ~/.codex/config.toml contains:
[mcp_servers.playwright]
command = "npx"
args = ["-y", "@playwright/mcp@0.0.84"]
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp@4.5.1"]
[mcp_servers.context7.env]
CONTEXT7_API_KEY = "your-key"
[mcp_servers.github]
url = "https://api.githubcopilot.com/mcp/"
bearer_token_env_var = "GITHUB_PAT"
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"Each server is a [mcp_servers.<name>] table. Local servers have command and args, plus an optional env table. Remote servers have url. You can edit this file directly; Codex reads it on the next start.
Notice that --env wrote the API key into the file in plain text. That's fine on your own laptop, but for anything shared, prefer servers that support OAuth or a bearer_token_env_var.
Check what's connected
codex mcp listCodex prints local and remote servers in two tables, including how each one authenticates:
Name Command Args Env Cwd Status Auth
context7 npx -y @upstash/context7-mcp@4.5.1 CONTEXT7_API_KEY=***** - enabled Unsupported
playwright npx -y @playwright/mcp@0.0.84 - - enabled Unsupported
Name Url Bearer Token Env Var Status Auth
figma https://mcp.figma.com/mcp - enabled Not logged in
github https://api.githubcopilot.com/mcp/ GITHUB_PAT enabled Bearer token"Unsupported" in the Auth column just means a local server doesn't use OAuth. "Not logged in" means you still need codex mcp login. To see one server's full settings, run codex mcp get github. To delete one, codex mcp remove github.
Windows and slow starts
On Windows, npx is a .cmd script, and launching it directly can fail. Start it through cmd instead. The Chrome DevTools MCP project documents this form for Codex on Windows 11, with a longer startup timeout for the first download:
[mcp_servers.chrome-devtools]
command = "cmd"
args = ["/c", "npx", "-y", "chrome-devtools-mcp@1.12.0"]
startup_timeout_ms = 20_000The same startup_timeout_ms key helps on any OS when a server is slow to start the first time, because npx downloads the package before it can run.
Check yourself
Codex CLI doesn't read JSON MCP config. Add the server with codex mcp add or as a [mcp_servers.<name>] table in ~/.codex/config.toml.
Use --bearer-token-env-var GITHUB_PAT when adding the server. Codex stores only the variable name and reads the token from your environment when it connects.
codex mcp login <name>, which opens the server's OAuth sign-in in your browser.