Codex as an MCP Client

Out of the box, Codex can read your files, search the code, run commands, and edit. Powerful — but every one of those tools points inward, at the repo in front of it. The moment a task needs something the repo doesn't contain — the current docs for a fast-moving library, a row from your production database, a Figma frame, a Jira ticket — Codex is blind.

MCP (the Model Context Protocol) is the universal adapter that fixes that. It's an open standard for connecting a model to external tools, resources, and prompts. Instead of OpenAI hand-building an integration for every service on earth, anyone can ship an MCP server that exposes their service, and any MCP client — Codex included — can plug into it. One protocol, many providers: the M×N integration problem collapses to M+N.

In this relationship Codex plays the client: it connects out to servers other people wrote and calls their tools as if they were its own. (Codex can also run the other way — as a server that other agents drive — but that's the next lesson. Here we're strictly the consumer.)

Think of it like USB-C for AI tooling. You don't rewire your laptop for every peripheral; you expose one port, and any compliant device speaks to it. MCP is that port for Codex.

Codex can talk to an MCP server over exactly two transports, and choosing between them is your first decision:

The rule of thumb: stdio for local tools (a CLI you npx/uvx into existence, a script on your machine), streamable HTTP for hosted services (a vendor running the server for you at https://…).

One accuracy note that catches people coming from other clients: the older SSE (HTTP+SSE) transport is not listed as supported by Codex — only stdio and streamable HTTP. If a server only advertises a legacy SSE endpoint, you'll want its stdio or streamable-HTTP variant. (Under the hood Codex's MCP stack is built on the Rust rmcp crate; you don't interact with that directly, but it's why streamable HTTP is a first-class, default path now rather than something you opt into.)

The fastest way to add a server is the codex mcp command group, which writes entries into ~/.codex/config.toml for you. You don't have to hand-edit TOML to get started.

stdio server — everything after the -- separator is the launcher command and its arguments:

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

The official, copy-pasteable example wires up Context7 (a live-docs server) via npx:

codex mcp add context7 -- npx -y @upstash/context7-mcp

Here context7 is the name you'll see in /mcp, and npx -y @upstash/context7-mcp is the command Codex will spawn. Pass --env KEY=VALUE (repeatable) for any environment variables the process needs.

Streamable HTTP / URL server — use --url instead of a -- launcher:

codex mcp add figma --url https://mcp.figma.com/mcp

HTTP servers usually need authentication. The codex mcp add flags that matter for that:

Note the bearer-token flag takes the name of an environment variable, not the token itself — Codex reads the secret from your environment so it never lands in config.toml in plaintext.

Once servers are registered, the rest of the codex mcp subcommands let you manage them without touching the config file:

A typical lifecycle looks like:

codex mcp add context7 -- npx -y @upstash/context7-mcp   # register
codex mcp list                                           # confirm it's there
codex mcp get context7 --json                            # inspect its config
codex mcp login figma --scopes files:read                # OAuth into an HTTP server
codex mcp remove context7                                # tear it down

For remote servers that use OAuth, codex mcp login <name> runs the browser login flow and stores the credentials; codex mcp logout <name> revokes them locally. Codex respects the scopes the server advertises, or falls back to the --scopes you pass (or the scopes in config).

The CLI is convenient, but every server ultimately lives as a [mcp_servers.<id>] table in ~/.codex/config.toml (global) — or in a project-scoped .codex/config.toml for a trusted project. Knowing the schema lets you review, version, and fine-tune entries by hand.

stdio server — a command (required) plus optional args, environment, and timeouts:

[mcp_servers.context7]
command = "npx"                 # required: the launcher
args = ["-y", "@upstash/context7-mcp"]
startup_timeout_sec = 10        # default 10s to initialize the server
tool_timeout_sec = 60           # default 60s per tool call

[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"     # env forwarded to the process

Streamable HTTP server — a url plus auth and headers:

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"   # token read from this env var
http_headers = { "X-Figma-Region" = "us-east-1" }   # static headers per request
# env_http_headers = { ... }   # headers populated from env vars
# scopes = ["files:read"]      # OAuth scopes to request
# oauth_resource = "..."         # RFC 8707 resource parameter

The key fields to know by transport:

Both timeouts are overridable per server, so a slow-starting server (a heavy local process) or a long-running tool can be given more room.

An MCP server can expose many tools, and you rarely want all of them, all the time. Codex gives you per-server controls that work for both stdio and HTTP servers:

The ordering matters: disabled_tools is applied after enabled_tools. So the final tool set is "everything in the allow-list, minus anything in the deny-list" — the deny-list always wins.

[mcp_servers.db]
command = "my-db-mcp"
enabled = true
required = false
enabled_tools = ["query", "describe_table"]   # only these two
disabled_tools = ["query"]                      # ...minus query -> only describe_table remains
default_tools_approval_mode = "prompt"          # ask before running its tools

[mcp_servers.db.tools.describe_table]
approval_mode = "auto"                           # but let this safe one run unprompted

Two behaviors worth internalizing. First, required = true is a sharp tool: it turns a flaky or misconfigured server into a hard startup failure, which is what you want in CI (fail loud) but not on your laptop (where you'd rather keep working). Second, read-only MCP tools that advertise the readOnlyHint are allowed to run in parallel, so well-behaved read tools don't serialize your turn.

After all the configuration, you need a way to confirm what Codex actually loaded. In the codex TUI, type:

/mcp

/mcp lists your active MCP servers and their status — which connected, which failed, and the tools they expose. It's the first thing to check when a server you expected isn't showing up, or when a tool call mysteriously isn't available.

A quick triage loop when an MCP tool isn't working:

1. /mcp in the TUI — is the server listed and healthy? If it's missing or errored, the problem is connection/config, not the model.
2. codex mcp get <name> — is the command, URL, or token env var what you expect?
3. Auth — for HTTP servers, did codex mcp login <name> succeed, and is the token env var actually set in this shell?
4. Gating — did enabled_tools/disabled_tools accidentally filter out the tool you wanted? Remember the deny-list is applied last.
5. Timeouts — a heavy server may be tripping the 10s startup_timeout_sec; raise it.

Because MCP server config is just part of Codex's config, the servers you set up are shared across Codex surfaces that read the same config.toml — set them up once and they follow you.