Codex MCP Setup: Add MCP Servers to OpenAI Codex (2026)

How to Add an MCP Server to Codex

To connect an MCP server to OpenAI Codex, run codex mcp add <name> -- <command> for a local (stdio) server or codex mcp add <name> --url <https-url> for a remote (streamable HTTP) server, then type /mcp in Codex to confirm it is connected. Every entry is saved as an [mcp_servers.<name>] table in ~/.codex/config.toml, and that one file is shared by the Codex CLI, the IDE extension and Codex in the ChatGPT desktop app.

This guide covers the whole workflow as of October 2026: the CLI commands, the exact config.toml keys, OAuth login, timeouts and tool approval, plus one change that trips up older tutorials — codex mcp-server (running Codex itself as an MCP server) has been removed. Everything below is checked against the official Codex MCP documentation and the Codex CLI reference.

Where Codex MCP Configuration Lives

Codex stores MCP servers in its normal config file:

The ChatGPT desktop app (which absorbed the standalone Codex app in July 2026), the Codex CLI and the IDE extension all read the same configuration for the same Codex host. Configure a server once in the terminal and it shows up in the app and the extension too.

If you have not installed the CLI yet, the official installer for macOS and Linux is:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Option 1: Add Servers with codex mcp add

The CLI is the fastest route. A local stdio server is anything Codex launches as a child process — usually an npx, uvx or docker command. Put the launch command after --:

# Context7: up-to-date library docs for coding agents
codex mcp add context7 -- npx -y @upstash/context7-mcp

Pass environment variables with --env (repeatable):

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

A remote server uses --url instead of a command. The two are mutually exclusive:

# OpenAI's public docs server (no auth)
codex mcp add openaiDocs --url https://developers.openai.com/mcp

# A server that expects a bearer token from an env var
codex mcp add example --url https://mcp.example.com/mcp --bearer-token-env-var EXAMPLE_TOKEN

The rest of the codex mcp family:

Inside an interactive codex session, /mcp lists active servers and tools, /mcp verbose adds per-server diagnostics, and /mcp login <name> signs in without leaving the session.

Option 2: Use the ChatGPT Desktop App or IDE Extension

If you prefer a form over the terminal:

• ChatGPT desktop app: Settings → MCP servers → Add server. Enter a name, choose STDIO or Streamable HTTP, provide the command or URL, save, then select Restart. OAuth servers show an Authenticate button.
• IDE extension: gear menu → MCP servers → Add server, save, then Restart extension.

Both write to the same config.toml, so you can mix and match. Note that hosted ChatGPT on the web does not read your local Codex config — it gets MCP tools through installed plugins instead. If that is what you need, see our ChatGPT MCP setup guide.

Option 3: Edit config.toml Directly

For anything beyond the basics — tool allow lists, approval modes, timeouts — edit the file. Each server is one table.

A 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"         # set a fixed value for the server

Stdio keys: command (required), args, env (fixed values), env_vars (names to allow and forward from your environment), and cwd (working directory).

A streamable HTTP server

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

HTTP keys: url (required), bearer_token_env_var (sent as Authorization: Bearer ...), http_headers (static headers), env_http_headers (header name mapped to an env var name), http_headers_helper (a local command that prints a JSON object of headers, refreshed once after a 401 or 403), and auth — oauth by default, or chatgpt to reuse your ChatGPT session for trusted first-party servers. If nothing resolves, Codex connects without credentials.

Timeouts, tool filters and approvals

[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

A top-level mcp_optional_startup_grace_ms (default 1000) controls how long Codex waits for optional servers before building the first tool list; set it to 0 to wait for each server's full startup_timeout_sec.

OAuth for Remote MCP Servers

Many hosted servers — for example Sentry, Notion and Linear — sign you in with OAuth rather than a static token. The flow in Codex:

1. Add the server with --url.
2. Run codex mcp login <name> (or click Authenticate in the app). A browser window opens; Codex listens on a loopback callback such as http://127.0.0.1/callback.
3. Approve access. Codex stores the credentials and reuses them.

Codex registers itself automatically, preferring Client ID Metadata Documents (CIMD) when the authorization server advertises support and falling back to Dynamic Client Registration (DCR). You can force one for a single login:

codex mcp login <server-name> --oauth-client-registration dcr

If your identity provider requires a pre-registered client, pass it when adding the server. Codex prints the exact callback URL to register with your provider:

codex mcp add example --url https://mcp.example.com --oauth-client-id my-client
# confidential client: read the secret from an env var
codex mcp add example --url https://mcp.example.com --oauth-client-id my-client --oauth-client-secret "$MCP_CLIENT_SECRET"

The secret is saved to mcp_servers.example.oauth.client_secret in config.toml, so keep that file out of version control. For remote dev boxes, the global mcp_oauth_callback_port and mcp_oauth_callback_url settings pin the callback. For the protocol side of this flow, read our MCP authentication and OAuth guide.

Can Codex Run as an MCP Server?

Not anymore. Older guides tell you to run codex mcp-server so another agent can drive Codex over MCP. That command was deprecated on August 24, 2026 and, together with the standalone codex-mcp-server binary, removed on September 5, 2026. OpenAI's replacement is the Codex app server, which speaks its own JSON-RPC protocol (not MCP) and is still marked experimental. If an Agents SDK script or orchestration tool launches codex mcp-server, pin an older Codex version or migrate before upgrading. Codex as an MCP client — everything else in this guide — is unaffected.

Good First Servers for Codex

Start with two or three. Every enabled server adds tool definitions to the context, and overlapping tools make selection worse — see how MCP clients discover tools.

Troubleshooting Codex MCP

• "Server failed to start" or timeout on first run. npx -y and uvx download packages on first launch, which can take longer than the 10-second default. Raise startup_timeout_sec to 30–60, or pre-install the package.
• Server starts but tools are missing. Run /mcp verbose. Check enabled_tools and disabled_tools — the deny list wins.
• API key not reaching the server. Add the variable name to env_vars, or set it under [mcp_servers.<name>.env]. For HTTP servers use bearer_token_env_var and make sure the variable is exported in the shell that starts Codex.
• Project servers ignored. .codex/config.toml only loads when the project is trusted.
• Long-running tools get cut off. Raise tool_timeout_sec for that server only.
• OAuth loop or invalid redirect_uri. Register the exact callback that codex mcp add printed, including any server-specific callback ID.
• Debug the server outside Codex. If a server misbehaves, isolate it with MCP Inspector before blaming the client.

Before giving a third-party server write access, read our MCP security best practices and prefer default_tools_approval_mode = "writes" or "prompt".

Codex vs Claude Code MCP Config at a Glance

The server packages are the same; only the wrapper changes. Our Claude Code MCP guide covers the other side.

Next Steps

Pick a server from the MCP server directory, add it with codex mcp add, and confirm with /mcp. Browse by category to find servers for your stack, or compare other MCP clients that can share the same servers.