MCP setup · OpenAI
How to add an MCP server to OpenAI Codex
Codex is the odd one out in this set: its configuration is TOML rather than JSON, which means a definition copied from any other surface's documentation needs translating rather than pasting. That friction is small, and it has one useful side effect worth naming.
How this surface handles MCP
Codex CLI reads configuration from `~/.codex/config.toml`, with a project-scoped `.codex/config.toml` for settings that should travel with a repository. MCP servers are declared as tables named `[mcp_servers.<server-name>]` — note the underscore, which is the detail that trips people who have been working in `mcpServers` all week.
The CLI covers the common paths: `codex mcp add` registers a server with environment variables passed through, `codex mcp list` shows what is configured, and `codex mcp login` handles OAuth for servers that require it. As with every surface here, `add` writes configuration rather than validating that the credential works, so a saved server and a working server are different claims.
The TOML format has a genuine, if minor, security upside. Because a definition cannot be copied verbatim from a blog post or a server's README, somebody has to read the fields and retype them. That is not a control and should not be mistaken for one — but the surfaces where a config blob is a single copy-paste are measurably the ones where nobody reads what they pasted.
What Codex does not give you, in publicly documented form, is an organisational policy surface for MCP comparable to Copilot's org switch or Cursor's enterprise allowlist. We are stating that as the limit of what we could verify rather than as a claim about the product: if you need central enforcement here, confirm the current position with OpenAI rather than taking a third party's word for it, including ours.
Where servers are stored
~/.codex/config.tomlreaches You, everywhere you run Codex on this machine.
The default location, and the one to audit first — it applies regardless of which repository you are in.
.codex/config.tomlreaches The project directory it sits in.
Committed and reviewable, which makes it the right home for anything the team shares.
The config shape
TOML, not JSON. Each server is a table named `[mcp_servers.<name>]`. Definitions from other surfaces need translating rather than pasting — the key is `mcp_servers` with an underscore.
OpenAI Codex — MCP server definition
[mcp_servers.example-server]
command = "npx"
args = ["-y", "@example/mcp-server@1.4.2"]
[mcp_servers.example-server.env]
EXAMPLE_MODE = "read-only"Adding a server
- Add a stdio server from the CLI
`codex mcp add <name> --env KEY=VALUE -- <command> [args...]`. Everything after the `--` is the server's own command line, which is the same separator convention Claude Code uses.
- Or write the TOML table directly
`[mcp_servers.<name>]` with `command` and `args`, and a nested `[mcp_servers.<name>.env]` table for environment variables. TOML's nesting rules are the part people get wrong, not the field names.
- Authenticate servers that need OAuth
`codex mcp login <server-name>` runs the OAuth flow. Do this before assuming a connection failure is a configuration error — an unauthenticated server fails in a way that looks like a broken definition.
- Pin the version
As on every other surface: an unpinned package launcher resolves at start time, so what you reviewed and what runs are not the same artifact and nothing records the divergence.
Confirming it actually connected
- Run `codex mcp list` and confirm the server appears with the definition you intended, including the environment it will receive.
- Check that the TOML parses — a misplaced nested table is the most common failure here, and it produces a config that loads without the server rather than an error.
- For OAuth servers, confirm `codex mcp login` completed. `codex mcp add` saves configuration without validating credentials, so 'configured' and 'connected' are separate states.
Review this before you connect anything
the part the vendor docs will not tell you
A connected MCP server can read what its credential can read and do what its tools can do, and its tool descriptions reach the model as instructions. None of that is visible from a configuration file that parses correctly.
- Read the tool descriptions before retyping them
The TOML translation step is a rare moment when somebody is actually looking at the definition. Spend it reading what the server's tools claim to do, because descriptions reach the model as instructions.
- Scope the credential first
The token decides the damage, and it is the same token whichever surface connects the server. Narrow it once and reuse the decision.
- Check whether this server is already approved elsewhere
If it is connected to your terminal agent or your editor, the review exists — reuse it. If it is not connected anywhere else, this is the first review, and it should be a real one.
- Record what you connected
Without a central policy surface to lean on, a written record of which servers are approved and at which versions is the difference between an inventory and a guess.
Organisational controls
- Project-scoped configuration
A committed `.codex/config.toml` gives a repository one reviewed definition that travels with it. That is a shared default rather than enforcement — a user-scoped server still applies alongside it.
- Credential scope as the practical control
Where a documented central policy surface is not available to you, the token is the control you do have. A server holding a narrowly scoped, short-lived credential has a bounded blast radius regardless of who connected it.
- Verify the current enterprise position directly
We are not publishing an admin click-path for Codex because we could not verify one from publicly reachable documentation. If central MCP policy is a requirement for you, ask OpenAI rather than relying on a third-party page — including this one.
What this cannot tell you
A TOML file in a home directory describes one machine's intent at one moment. It cannot tell you which servers your other engineers have added, whether an unpinned launcher has resolved to something new since the review, or whether the same server is connected — with a wider credential — to a different AI surface on the same laptop.
Frequently asked
- Where is the Codex config file?
- `~/.codex/config.toml` by default, with a project-scoped `.codex/config.toml` for settings that should live alongside a repository.
- What is the TOML table for MCP servers in Codex?
- `[mcp_servers.<server-name>]`, with an underscore rather than the camel-case `mcpServers` key that Claude Code, Cursor and Gemini CLI use. Environment variables go in a nested `[mcp_servers.<name>.env]` table.
- How do I add an MCP server to Codex from the command line?
- `codex mcp add <name> --env KEY=VALUE -- <command> [args...]`. Use `codex mcp list` to check what is registered and `codex mcp login <name>` for servers that require OAuth.
- Can an organisation centrally control which MCP servers Codex connects to?
- We could not verify a documented central MCP policy surface for Codex from publicly reachable documentation, so we are not describing one. Confirm the current position with OpenAI. In the meantime, credential scope and a written approved-server list are the controls actually available to you.
Sources
Every path, key, table and flag on this page was read from OpenAI's own documentation on 2026-07-26. Where a control varies by plan or is changing quickly, this page describes the mechanism rather than asserting a current state.