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

Codex MCP cover

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:

Terminal
# 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 --help

The -- 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:

TOML
[mcp_servers.my-server]
# settings go here

Config 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:

Terminal
codex mcp add context7 \n  -- npx -y @upstash/context7-mcp

Or add it to config.toml yourself:

TOML
[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:

TOML
[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:

Terminal
codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp

The same thing in ~/.codex/config.toml:

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:

TOML
[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:

Terminal
export FIGMA_OAUTH_TOKEN="your-token"
PowerShell
$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:

TOML
[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 = true

Because 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:

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:

  1. Open the gear menu.
  2. Select MCP servers.
  3. Select Add server and fill in the details.
  4. 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.

Build it with us in Stride AI Academy

Four courses, weekly live calls and a community of people building and selling AI. Or start with 320+ free guides.

Keep reading

Free AI Coding guides