MCP in Codex: Client, Server & Tool Governance

Codex out of the box can read your files, run your shell, and edit your repo. The instant a task reaches past that boundary — a Context7 doc lookup, a row in production Postgres, a Sentry issue, your own internal API — the agent is blind, and you go back to copy-pasting between Codex and the other tool.

The Model Context Protocol (MCP) is the open standard that deletes that courier work. You register a server once; Codex then calls its tools directly, inside the same session, with no paste in the middle. Codex plays both roles in the protocol: it is an MCP client (it connects out to servers you add) and an MCP server (other apps connect into Codex with codex mcp-server). This guide covers both directions, plus the part most teams skip until it bites them — tool governance: deciding exactly which tools a server may expose and which ones run without asking.

Two transports: stdio vs HTTP

Every server you add speaks to Codex over one of two transports, and the transport is implied by how you add it. There is no --transport flag — you pick stdio by passing a launch command after --, or HTTP by passing --url.

stdio runs the server as a local child process on your machine, exchanging JSON-RPC over standard input/output. Use it for tools that need direct system access or ship as a local package — the canonical example is codex mcp add context7 -- npx -y @upstash/context7-mcp. The -- is load-bearing: everything after it is the command Codex spawns, untouched. Drop the -- and Codex tries to parse the server's own flags as its own and the add fails.

Streamable HTTP points Codex at a remote endpoint with --url. This is the path for cloud services and anything behind OAuth. It is the only transport that supports the codex mcp login OAuth flow covered later — stdio servers authenticate with environment variables instead.

The four management commands

Adding is one of five codex mcp subcommands. The other four are the daily workflow [V]:

• codex mcp list — every configured server with its transport and command/URL. Add --json for machine-readable output you can pipe into scripts.
• codex mcp get <name> — one server's full stored entry. --json prints the raw config.
• codex mcp remove <name> — deletes the stored definition.
• codex mcp login <name> / codex mcp logout <name> — the OAuth pair for HTTP servers (next section).

Whatever you do through the CLI is just a thin writer over config.toml. codex mcp add writes a [mcp_servers.<name>] table; codex mcp remove deletes it. You can hand-edit that file instead and Codex picks it up identically — which is the right move once a server needs the governance keys the CLI flags don't expose.

The [mcp_servers.id] schema, in full

This is the artifact that actually matters: the [mcp_servers.<id>] table in ~/.codex/config.toml. A stdio server uses command/args/env; an HTTP server uses url and its header/token keys. The two halves below show every documented key. [V]

Tool governance: enabled_tools, disabled_tools, approval modes

A busy MCP server can hand Codex twenty tools when you wanted three, and some of those twenty write — they drop tables, push commits, send messages. Governance is how you bound that surface. Codex gives you two independent levers. [V]

Which tools exist at all is controlled by two lists. enabled_tools is an allow-list: set it, and only the named tools are exposed — everything else on the server is invisible to Codex. disabled_tools is a deny-list applied after enabled_tools. That ordering is the rule to memorize: deny wins. If a tool name appears in both, it stays hidden. A common, safe pattern is to allow-list the read tools and deny-list the one dangerous write you can't fully trust.

Which tools run without asking is controlled by approval modes, with three values: auto (run silently), prompt (ask you each time), and approve (require explicit approval). default_tools_approval_mode sets the baseline for every tool on that server. Then [mcp_servers.<id>.tools.<tool>] with its own approval_mode overrides the default for one specific tool. So the idiomatic stance — ask before anything, except let the obviously-safe read tool run free — is exactly default_tools_approval_mode = "prompt" plus a per-tool approval_mode = "auto" on the read tool, as shown in the schema above.

OAuth for HTTP servers

Many remote servers won't take a static bearer token — they want a real OAuth flow. Codex handles this for streamable-HTTP servers only, with the login/logout pair. [V]

codex mcp login <name> opens a browser, runs the OAuth dance, and stores the resulting credentials so the server connects on every future session without re-auth. If the server gates capabilities behind scopes, request them with --scopes scope1,scope2. To revoke, codex mcp logout <name> deletes the stored credentials for that server.

Two knobs shape the flow. The callback is a local port the browser redirects back to — override it with the top-level mcp_oauth_callback_port in config.toml if the default collides with something. And where credentials live is controlled by mcp_oauth_credentials_store, which takes auto, keyring, or file. On a laptop, keyring stores tokens in the OS secret store (Keychain / libsecret); file writes them to disk, which is what you'll reach for on a headless box with no keyring daemon. auto lets Codex choose.

Codex as a server: codex mcp-server

Flip the protocol around. codex mcp-server runs Codex itself as an MCP server over stdio, so another MCP client — a different agent, an IDE, an orchestration script — can drive Codex as a tool. It inherits your global config overrides and exits cleanly when the downstream client closes the connection. [V]

It exposes two tools to whoever connects:

• codex — start a new Codex session. The client passes a prompt and configuration; Codex runs the turn and returns its output.
• codex-reply — continue an existing session. This is the multi-turn primitive.

Continuation hangs on one value: threadId. When you call the codex tool, the response carries structuredContent.threadId; you feed that same threadId into codex-reply to keep talking in the same thread, with full context preserved. (conversationId is a deprecated alias kept for backward compatibility — use threadId.) This is the exact mechanism the upcoming MCP-bridge tandem guide uses to let Claude Code call Codex as a sub-agent: Claude is the client, codex mcp-server is the server, and threadId threads the conversation. [V]

Enterprise lockdown: requirements.toml

On a single laptop, you decide what Codex connects to. In an org, an admin does — and the mechanism is requirements.toml, a file of constraints users cannot override. It lives at /etc/codex/requirements.toml on Linux/macOS and %ProgramData%\OpenAI\Codex\requirements.toml on Windows. [V]

For MCP, the admin adds an [mcp_servers] table that acts as a strict allow-list keyed by identity. For stdio servers the identity matches on command; for HTTP servers it matches on url. A server is permitted only when both its config name and its identity match an approved entry — and if the table is present but empty, all MCP servers are disabled. That empty-table-means-deny-all behavior is the safe default to know: a locked-down fleet ships every developer the same vetted set and nothing else.

# /etc/codex/requirements.toml  (admin-managed; users cannot override)
[mcp_servers.docs]
identity = { command = "codex-mcp" }
 
[mcp_servers.remote]
identity = { url = "https://example.com/mcp" }

The same file also governs approval policies, sandbox modes, permission profiles, and command rules — MCP is one slice of a broader managed-configuration surface. If your codex mcp add silently fails to enable a server in a managed environment, this allow-list is the first place to look.