# How to Add an MCP Server to Codex CLI (2026 Guide) > Add an MCP server to Codex CLI via config.toml or codex mcp add — remote and local servers, bearer tokens, and fixing servers that won't load. Source: https://designrevision.com/blog/add-mcp-server-to-codex --- To add an MCP server to the OpenAI Codex CLI, add a `[mcp_servers.]` 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](/blog/add-mcp-server-to-cursor) or the `claude mcp add` CLI of [Claude Code](/blog/add-mcp-server-to-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.]` 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](/mcp)**, a server that installs [shadcn/ui components](/components) into your project. Add this to `~/.codex/config.toml`: ```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): ```bash 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: ```bash 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: ```toml [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: ```toml [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.]` 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: ```bash codex mcp list ``` That prints every configured server and its status; `codex mcp get ` 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 `. ## 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](/blog/best-mcp-servers-for-codex). (The same servers work across agents; only the TOML config is Codex-specific, so our [Claude Code roundup](/blog/best-mcp-servers-for-claude-code) 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.]` 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 - [Best MCP Servers for Codex (2026): Ranked](/blog/best-mcp-servers-for-codex) - [DesignRevision MCP — the shadcn/ui MCP server](/mcp) - [How to Add an MCP Server to Claude Code (2026 Guide)](/blog/add-mcp-server-to-claude-code) - [How to Add an MCP Server to Cursor (2026 Guide)](/blog/add-mcp-server-to-cursor) - [How to Add an MCP Server to Windsurf (2026 Guide)](/blog/add-mcp-server-to-windsurf) - [Claude Desktop MCP Config: How to Add a Server (2026)](/blog/claude-desktop-mcp-config) - [Best MCP Servers for Claude Code (2026): Tested & Ranked](/blog/best-mcp-servers-for-claude-code) - [Browse the shadcn/ui component registry](/components)