Blog Guides Alternatives Compare
Back to Blog
AI

How to Add an MCP Server to Codex CLI (2026 Guide)

View as Markdown Open in ChatGPT Open in Claude
DesignRevision Editorial DesignRevision Editorial · SaaS, frontend & developer tooling
• 7 min read
Human Written
Share:

To add an MCP server to the OpenAI Codex CLI, add a [mcp_servers.<name>] table to ~/.codex/config.toml, or run codex mcp add. Codex speaks both local servers (stdio subprocesses) and remote servers (streamable HTTP) natively, so a single config entry gives its agent a new set of tools. The one thing to get right up front: Codex's config is TOML, not JSON — the format Claude Code and Cursor use won't work here. This guide covers both methods, the exact config for remote and local servers, and how to fix a server that won't load.

Last updated: July 2026. Codex's MCP support has moved fast (native HTTP landed in late 2025); everything here was verified against OpenAI's Codex docs in July 2026 — check github.com/openai/codex if a field has changed.

An MCP server exposes tools that Codex's agent can call. Configuring one in Codex looks different from other agents: it's TOML tables, not the JSON of Cursor or the claude mcp add CLI of Claude Code. The mechanics below are Codex-specific.

The Two Ways to Add an MCP Server to Codex

Codex gives you a CLI and a config file, and they do the same thing:

  1. The codex mcp add command — Codex writes the TOML for you. Fastest for a one-off add.
  2. Editing ~/.codex/config.toml — you write the [mcp_servers.<name>] table yourself. More control, and easy to review or commit.

Under the hood the CLI just edits config.toml, so once you can read the file, both make sense. We'll show each for the two server types.

Add a Remote MCP Server (HTTP)

Most hosted servers are remote. Codex connects over streamable HTTP when you give the table a url, and it handles bearer-token auth through an environment variable — you never hard-code the token in the file. Here's a real example adding DesignRevision MCP, a server that installs shadcn/ui components into your project.

Add this to ~/.codex/config.toml:

[mcp_servers.design-revision]
url = "https://mcp.designrevision.com/mcp"
bearer_token_env_var = "DESIGNREVISION_API_KEY"

Then set the token in your shell (add it to your ~/.zshrc or ~/.bashrc to make it permanent):

export DESIGNREVISION_API_KEY="your-token-here"

Codex reads that variable at runtime and sends it as an Authorization: Bearer header automatically. The equivalent one-liner, which writes the same TOML for you, is:

codex mcp add design-revision --url https://mcp.designrevision.com/mcp --bearer-token-env-var DESIGNREVISION_API_KEY

Two accuracy notes that most guides — and even Google's AI Overview — get wrong. The table key is mcp_servers with an underscore ([mcp_servers.design-revision]), not mcp.servers. And you do not need the old mcp-remote bridge to reach a remote server: native HTTP has been built in since late 2025. (If you're on a much older Codex build or hitting Windows HTTP quirks, wrapping the URL in npx -y mcp-remote as a stdio server still works as a fallback — but it isn't the 2026 method.) For servers that use a non-standard header instead of a bearer token, use http_headers (static) or env_http_headers (from env vars) in place of bearer_token_env_var.

Add a Local MCP Server (stdio)

Local servers run as a subprocess. Give the table a command, its args, and an optional env block for secrets:

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "~/code"]

The CLI form is codex mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/code — everything after -- is the launch command. command can be npx, uvx, python, node, or docker. When a local server needs a secret, add it to an env table:

[mcp_servers.some-tool]
command = "npx"
args = ["-y", "some-mcp-server"]
env = { "API_KEY" = "your-key" }

Where Codex Keeps Your MCP Config

Everything lives in ~/.codex/config.toml — a single TOML file in your home directory. Two things worth knowing:

  • Codex doesn't create it for you. If the file doesn't exist yet, make it; the codex mcp add command will create it on first use.
  • It's shared across surfaces. The Codex CLI, the IDE extension, and the desktop app all read the same config.toml, so a server you add once shows up everywhere.

Because it's TOML, each server is its own [mcp_servers.<name>] table — you can stack as many as you like, one table each.

Verify and Manage Your Servers

After adding a server, confirm Codex picked it up:

codex mcp list

That prints every configured server and its status; codex mcp get <name> shows one server's full config. Inside the Codex TUI, the /mcp slash command lists connected servers and the exact tools each one exposes — the quickest way to confirm the agent can actually see them. To remove a server, run codex mcp remove <name>.

Troubleshooting: When a Codex MCP Server Won't Load

Work through these in order — they cover almost every case:

  • JSON instead of TOML. The most common mistake by far. Codex uses TOML tables ([mcp_servers.name]), not a JSON mcpServers object. Retype it as TOML.
  • Wrong table key. It must be mcp_servers (underscore), not mcp.servers. A wrong key means Codex silently ignores the server.
  • Startup timeout. Codex gives a server ~10 seconds to boot (startup_timeout_sec). A cold npx install can exceed that and fail silently — raise it: startup_timeout_sec = 30 in the server's table.
  • Missing token → 401. For remote servers, if the env var named in bearer_token_env_var isn't set in the shell you launched Codex from, auth fails. Confirm with echo $DESIGNREVISION_API_KEY.
  • Connected but no tools. If codex mcp list shows the server up but the agent sees nothing, it's usually a transport/handshake mismatch — double-check the URL (a trailing-slash difference can matter) and that it's a streamable-HTTP endpoint.
  • Windows + HTTP. Streamable HTTP is the roughest edge on Windows; if a remote server is flaky there, the stdio mcp-remote fallback is more reliable.

Which MCP Servers Should You Add to Codex?

Adding a server is easy; a focused set is what makes the agent genuinely useful. GitHub, Context7, Playwright, and a database server cover most workflows, and DesignRevision MCP adds the one thing the others don't: installing real shadcn/ui components on request. We rank the ten most useful ones — each with a verdict and its exact config.toml block — in our roundup of the best MCP servers for Codex. (The same servers work across agents; only the TOML config is Codex-specific, so our Claude Code roundup covers the same ground for that client.)

Conclusion

Adding an MCP server to Codex comes down to one TOML file — ~/.codex/config.toml — whether you write the [mcp_servers.<name>] table yourself or let codex mcp add do it. Remote servers need a url plus a bearer_token_env_var; local ones need a command. Keep tokens in environment variables, run codex mcp list to confirm the connection, and remember it's TOML, not JSON. Start with one server that fills a real gap and grow from there.

Related Resources

Frequently Asked Questions

Yes. The OpenAI Codex CLI is a full MCP client and connects to both local servers (stdio subprocesses) and remote servers (streamable HTTP) natively. You configure them in ~/.codex/config.toml or with the codex mcp add command, and Codex's agent can then call each server's tools during a task.

Two ways. Run codex mcp add --url --bearer-token-env-var for a remote server, or codex mcp add -- for a local one. Or edit ~/.codex/config.toml directly and add a [mcp_servers.] table. Both do the same thing; the CLI just writes the TOML for you.

At ~/.codex/config.toml in your home directory. It is TOML, not JSON, and Codex does not create it at install — you make it yourself. The same file is shared across the Codex CLI, the IDE extension, and the desktop app, so a server you add once is available everywhere.

Yes, natively. Give the server table a url and a bearer_token_env_var, and Codex connects over streamable HTTP and sends the token as an Authorization: Bearer header for you. You do not need the mcp-remote bridge that older setups used — that is only a fallback for legacy builds or rough Windows cases.

TOML. This trips people up constantly, because Claude Code and Cursor use JSON. Pasting a JSON mcpServers block into Codex's config.toml will not work — you need TOML tables like [mcp_servers.github]. Also note the correct key is mcp_servers (underscore), not mcp.servers.

Common causes: the config uses JSON or the wrong table key (it must be [mcp_servers.]); the server booted too slowly and hit the 10-second startup timeout (raise startup_timeout_sec); the bearer-token env var is unset, so auth returns 401; or the server connects but exposes no tools (a known handshake bug). Run codex mcp list to check status.

Run codex mcp list to see every configured server, or codex mcp get for one server's details. Inside the Codex TUI, the /mcp slash command shows connected servers and the tools each one exposes. Use codex mcp remove to delete one.

Start with a focused few — GitHub for repos and PRs, Context7 for up-to-date library docs, Playwright for browser testing, and DesignRevision MCP for installing real shadcn/ui components. The same servers used with Claude Code and Cursor work with Codex; only the config format (TOML) differs.

Join 50k+ subscribers

Web dev, SaaS, growth & marketing. Weekly.

Thanks for subscribing! Check your email.

No spam, unsubscribe anytime.

Back to all articles

Keep Learning

More articles you might find interesting.