Connect an MCP server to Codex
OpenAI's Codex CLI configures MCP in TOML — [mcp_servers] tables in ~/.codex/config.toml — or with one codex mcp add command that
writes the same file. Remote servers take a URL; local servers take a launch command. Every brand page here tells you which kind you're dealing with.
Local (stdio) servers
The quick way is the command:
codex mcp add example -- npx -y @vendor/mcp-server
# see what's configured
codex mcp listOr write the TOML yourself. Note the syntax differences from every other client's JSON:
tables instead of nested objects, and env as its own table:
[mcp_servers.example]
command = "npx"
args = ["-y", "@vendor/mcp-server"]
[mcp_servers.example.env]
VENDOR_API_KEY = "sk-…"Python servers use uvx as the command. To pass through variables already set in
your shell instead of writing values into the file, list them in env_vars = ["VENDOR_API_KEY"].
Remote (hosted) servers
Swap command for url. Authentication defaults to OAuth — Codex
sends you through the vendor's sign-in when you run codex mcp login:
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"codex mcp login figmaFor servers that take a token instead of OAuth, point at an environment variable rather than pasting the secret into the file:
[mcp_servers.example]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "EXAMPLE_TOKEN"Servers you can add this way right now: fal.ai, Atlassian, Datadog, Buffer, Google Drive, Confluence.
Useful per-server options
| Option | Does |
|---|---|
| enabled = false | Turns a server off without deleting its config |
| enabled_tools / disabled_tools | Filters which of the server's tools Codex sees |
| default_tools_approval_mode | auto, prompt, writes or approve — when Codex asks before a call |
| startup_timeout_sec / tool_timeout_sec | Raises timeouts for slow-starting servers or long-running tools |
| http_headers | Extra headers for remote servers |
When it doesn't work
| Symptom | Usual cause | Fix |
|---|---|---|
| Server never appears | Invalid TOML | Table headers are [mcp_servers.name] — dots, not slashes; strings quoted |
| Appears, fails to start | npx not on PATH | Use the absolute path from which npx |
| Starts, then exits | Missing API key | Add it under [mcp_servers.name.env] or list it in env_vars |
| Remote server 401s | No auth established | Run codex mcp login <name>, or set bearer_token_env_var |
| Server slow, gets killed | Default startup timeout | Raise startup_timeout_sec for that server |
To see why a local server is failing, run its command directly in a terminal — the error it prints there is the one Codex is swallowing.
A word on trust
An MCP server runs with the credentials you give it, and Codex will act on whatever the
server returns. Prefer official servers where they exist,
give community ones scoped, revocable keys, and keep the approval mode away from auto for anything that writes. More in our MCP security guide.
Questions
Where is the Codex MCP config file?
~/.codex/config.toml — servers live in [mcp_servers.<name>] tables. codex mcp add writes to the same file, so you can mix the command and hand-editing freely.
Does Codex support remote MCP servers?
Yes. Give the server a url instead of a command, and Codex connects over streamable HTTP. Auth defaults to OAuth — run codex mcp login <name> to sign in — or set bearer_token_env_var to send a token from your environment instead.
How do I temporarily disable a server without deleting it?
Set enabled = false in its [mcp_servers.<name>] table. The config stays intact and one line flips it back on.
Can I limit which tools a server exposes to Codex?
Yes — enabled_tools and disabled_tools arrays on each server filter its tool list, and default_tools_approval_mode controls when Codex asks before calling one (auto, prompt, writes, or approve).
Does the Codex IDE extension use the same servers?
It reads the same configuration. In the extension, open the gear menu → MCP servers to manage them from the UI; changes need an extension restart to take effect.