Connecting the Codex CLI to an MCP Server

The Codex CLI ships a dedicated codex mcp subcommand for working with Model Context Protocol servers — but the more useful question for most people isn't "how do I invoke it," it's "what actually changes about how Codex behaves once an MCP server is connected," because the answer touches approvals, sandboxing and tool-call safety in ways that aren't obvious from the subcommand's name alone.

What an MCP server actually adds

An MCP server exposes tools to Codex the same way its own built-in file, shell and search tools are exposed — as callable actions with a name, a description, and a schema for their arguments. Once connected, those tools show up alongside Codex's native ones and can be invoked as part of an agentic session exactly like any other tool call. That's the entire point of the protocol: it lets you extend what Codex can do without touching Codex's own code, by pointing it at a server that implements the protocol on the other end.

Where to start

Run codex mcp --help inside your terminal before doing anything else. Subcommand syntax and available flags are the kind of detail that changes across CLI releases faster than a general guide can track reliably — the CLI's own help output, and the config file reference at learn.chatgpt.com/codex/config-file/config-reference, are the two sources this site trusts for exact flag names on any given version. What's stable and worth understanding up front is the behaviour around MCP tool calls, which is documented at the security and approvals level rather than the flag level, and changes far less often.

The approval behaviour that actually matters

This is the part worth reading closely before you connect anything. Destructive tool calls — the ones a server marks with a destructive annotation — always require approval from you, regardless of what sandbox or approval mode you're otherwise running under, and even if that same tool call also happens to carry a read-only hint. In plain terms: an MCP server telling Codex "this action is destructive" is a stronger signal than your own --ask-for-approval never flag, and Codex will still stop and ask. That's a deliberate design choice, not a bug you're meant to work around, and it means the safety of an MCP integration depends partly on whether the server you're connecting actually annotates its tools honestly.

Scoping what the server can reach

An MCP server is a separate process with its own permissions, separate from Codex's own sandbox. Connecting a server doesn't automatically grant it Codex's read/write scope, and it doesn't inherit Codex's sandbox restrictions either — a misconfigured or overly permissive MCP server can, in principle, do things Codex itself would have refused to do directly. Before connecting an unfamiliar server, it's worth asking the same question you'd ask of any third-party tool with filesystem or network access: what does it actually claim to need, and does that match what you're using it for.

A sane first session

Connect one server at a time rather than wiring up several before you've seen how any of them behave. Start a session in the default Auto sandbox posture — workspace-write with on-request approvals — so you get a prompt the first time the new server's tools are actually invoked, rather than discovering what they do after the fact. Watch what gets asked for approval; if a tool call from the new server is asking for something outside what you expected it to need, that's the moment to stop and re-read what the server actually does, not the moment to grant blanket approval to make the prompts stop.

Debugging a server that isn't showing up

If a connected MCP server's tools don't appear in a session, the most common causes are a server that isn't actually running or reachable at the address Codex was configured with, a schema the server exposes that Codex can't parse, or a config entry that's syntactically valid but pointed at the wrong process. codex mcp and the config reference are the two places to look first — and because MCP itself is an open protocol independent of any one CLI, testing the server directly with another MCP-compatible client can help isolate whether the problem is the server or the Codex-side configuration.

Why this belongs in the CLI guides, not the sandbox guides

MCP integration touches sandboxing and approvals, but it's fundamentally a workflow decision — what capabilities you're choosing to hand an agentic session — rather than a security-configuration decision on its own. The AltPlusCtrl guides on driving Codex from your actual terminal setup are a natural next stop once an MCP server is wired in and you're thinking about how the whole session fits into your day-to-day workflow, not just what it's technically allowed to touch.

Connecting more than one server

Once a first server is working the way you expect, adding a second is a smaller decision than the first one was — you already know what "watch the approval prompts closely for the first session" looks like in practice. The one thing worth re-doing every time regardless: connect the new server alone first, run one representative task against it, and only then go back to running multiple servers together. Debugging an unexpected approval prompt is straightforward when you know it came from the server you just added; it's much harder once three servers' tools are all live at once and any of them could be the source.

A note on cost

Nothing about connecting an MCP server changes how a request is priced on OpenAI's side — the tokens spent describing an MCP server's available tools to the model count as ordinary input tokens, the same as Codex's own built-in tool descriptions do. A session with several MCP servers connected, each exposing a handful of tools, can meaningfully grow the fixed per-request overhead before you've sent a single line of your own prompt, simply because every tool's name, description and argument schema has to be included so the model knows the tool exists. If you're running a cost-sensitive workflow, it's worth checking how many tools a newly connected server actually exposes — a server with a large surface area can add real, unavoidable input-token weight to every single request in the session, whether or not any of its tools ever actually get called.

When not to connect one at all

Not every capability needs to become an MCP server. If what you actually want is a one-off script Codex can run directly through its own shell access, wiring up a persistent MCP connection is more setup and more standing surface area than the task calls for — the sandbox and approval flags already covered elsewhere in this section handle that case more simply, with fewer moving parts to reason about later.