Codex MCP Setup: Add MCP Servers to the CLI and IDE
Codex MCP setup: add servers with codex mcp add or config.toml, connect STDIO and HTTP servers, log in with OAuth, and see how it differs from Claude Code.
Josh Pocock6 min read
AI Coding
Codex MCP
Stride AI Academy
To add an MCP server to Codex, run codex mcp add <name> followed by the server's start command for a local server, or codex mcp add <name> --url <url> for a remote one. Codex saves the server in ~/.codex/config.toml under an [mcp_servers.<name>] table, and you can also write that table by hand. The Codex CLI, IDE extension and ChatGPT desktop app share the same MCP config, so you set a server up once.
This guide covers the codex mcp commands, the config.toml syntax for local and remote servers, three working examples, OAuth login, tool filters and how Codex's setup differs from Claude Code's. Everything here was checked against OpenAI's Codex MCP docs, the Codex config reference, the OpenAI Docs MCP page and Claude Code's MCP docs on November 22, 2026. OpenAI's old developers.openai.com/codex links now redirect to learn.chatgpt.com.
The codex mcp commands
These are the commands the Codex MCP docs show:
# Add a local (STDIO) server, with optional environment variables
codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 \n -- <stdio server-command>
# Add a remote server by URL
codex mcp add <server-name> --url https://mcp.example.com/mcp
# List configured servers
codex mcp list
# Sign in to a server that uses OAuth
codex mcp login <server-name>
# See every MCP command
codex mcp --helpThe -- separates Codex's own flags from the command that starts the server. Anything after it is passed to the server as is.
Inside the Codex terminal UI, type /mcp to see which servers are active.
Where Codex stores MCP servers
By default, servers go in your user config at ~/.codex/config.toml. To limit a server to one project, put it in .codex/config.toml in that repo. Codex only loads project .codex/ files when you trust the project. Our Codex config.toml guide covers the rest of the file, including precedence between user and project config.
Each server is its own TOML table:
[mcp_servers.my-server]
# settings go hereConfig keys for local (STDIO) servers
A STDIO server is a program Codex starts on your machine.
| Key | What it does |
|---|---|
command |
Required. The command that starts the server. |
args |
Arguments passed to the command. |
env |
Environment variables to set for the server. |
env_vars |
Variables to allow and forward from your environment. |
cwd |
Working directory for the server. |
Config keys for remote (HTTP) servers
A streamable HTTP server runs somewhere else and Codex connects by URL.
| Key | What it does |
|---|---|
url |
Required. The server address. |
bearer_token_env_var |
Environment variable holding a bearer token for the Authorization header. |
http_headers |
Static header names and values. |
env_http_headers |
Header names mapped to environment variable names. |
auth |
Defaults to oauth. chatgpt is for trusted first-party ChatGPT servers. |
Options for every server
| Key | Default | What it does |
|---|---|---|
enabled |
Set to false to switch a server off without deleting it. |
|
required |
When true, Codex fails to start if this enabled server isn't ready. |
|
startup_timeout_sec |
10 |
How long to wait for the server to start. |
tool_timeout_sec |
60 |
How long each tool call can run. |
enabled_tools |
Allow list of tool names. | |
disabled_tools |
Deny list, applied after enabled_tools. |
Example 1: Context7 (local server)
Context7 gives the agent up-to-date library documentation. Add it with one command:
codex mcp add context7 \n -- npx -y @upstash/context7-mcpOr add it to config.toml yourself:
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["LOCAL_TOKEN"]The env_vars line forwards LOCAL_TOKEN from your shell to the server. To set a value directly instead, use an env subtable:
[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"Keep real secrets in your environment, not in the file, especially in a project config you commit.
Example 2: OpenAI Docs MCP (remote server)
OpenAI runs a public MCP server that searches and reads its developer docs. The docs page gives this command:
codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcpThe same thing in ~/.codex/config.toml:
[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"This is the simplest remote setup: a name and a URL.
Example 3: Figma (remote server with a token and header)
For a server that needs a token, point Codex at an environment variable rather than pasting the token in. The Codex docs show this for Figma:
[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 reads FIGMA_OAUTH_TOKEN and sends it as a bearer token, and adds the static X-Figma-Region header to each request. Set the variable before you start Codex:
export FIGMA_OAUTH_TOKEN="your-token"$env:FIGMA_OAUTH_TOKEN = "your-token"Limiting which tools a server exposes
Big servers can expose dozens of tools. Use enabled_tools and disabled_tools to keep only what you need. From the docs:
[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"]
startup_timeout_sec = 20
tool_timeout_sec = 45
enabled = trueBecause disabled_tools applies after enabled_tools, this server ends up with only open.
Signing in to OAuth servers
Many remote servers use OAuth. Sign in from the terminal:
codex mcp login <server-name>On a machine with no local browser, add --no-browser, open the printed URL somewhere else, then paste the full redirect URL back into the terminal. You can set scopes for one login with --scopes read,write, or set scopes under the server's table in config.toml. If you don't, Codex uses the scopes from the server's login challenge.
In the desktop app or IDE extension, use the Authenticate button instead.
Adding MCP servers in the Codex IDE extension
The IDE extension reads the same config, so servers you added in the CLI already work there. To add one from the extension:
- Open the gear menu.
- Select MCP servers.
- Select Add server and fill in the details.
- Select Restart extension.
Codex MCP vs Claude Code MCP
The ideas are the same. The commands and files differ.
| Codex | Claude Code | |
|---|---|---|
| Add a local server | codex mcp add, then the command after a double hyphen |
claude mcp add, then the command after a double hyphen |
| Add a remote server | codex mcp add name --url URL |
claude mcp add --transport http name URL |
| User config | ~/.codex/config.toml |
~/.claude.json |
| Project config | .codex/config.toml (trusted projects) |
.mcp.json in the project root |
| Format | TOML tables | JSON |
| Check status | /mcp |
/mcp |
Claude Code has three scopes, set with --scope: local (the default, this project only), project (shared through .mcp.json) and user (all your projects). It asks for approval before using project servers from .mcp.json. Codex uses user config plus project config that loads only in trusted projects.
The same Context7 server in Claude Code's .mcp.json would be JSON instead of TOML. See how to add an MCP server to Claude Code for the full walkthrough, and the best MCP servers for Claude Code for servers worth adding to either tool. If you're new to Codex, start with the Codex CLI tutorial.
Learn to build with Claude Code
The Stride AI Coding course teaches Claude Code and Codex for building client tools, written for non-programmers, with weekly live calls to review your builds. Many of the free guides cover Claude Code and Codex setups, and the Claude Code community is where members compare theirs.
FAQ
How do I add an MCP server to Codex?
Run codex mcp add <name> with the server's start command after a double hyphen for a local server, or codex mcp add <name> --url <url> for a remote one. You can also add an [mcp_servers.<name>] table to ~/.codex/config.toml by hand.
Where is the Codex MCP config file?
User-level servers live in ~/.codex/config.toml. Project servers go in .codex/config.toml in the repo, which Codex only loads for trusted projects.
Does the Codex IDE extension use the same MCP servers as the CLI?
Yes. The ChatGPT desktop app, Codex CLI and IDE extension share MCP configuration. A server you add in one shows up in the others.
How do I pass an API key to a Codex MCP server?
For local servers, forward it with env_vars or set it in an env subtable. For remote servers, use bearer_token_env_var to read a token from an environment variable, or env_http_headers for custom headers.
How do I turn off a Codex MCP server without deleting it?
Set enabled = false in that server's table in config.toml. Set it back to true to turn it on again.