Codex as an MCP Server

Everywhere else in this module, Codex is the MCP client: you point it at a server with codex mcp add, and Codex calls that server's tools — Context7 for docs, Figma for designs, a database connector for SQL. The arrow points outward from Codex.

This lesson flips the arrow. With one command, Codex becomes an MCP server, and other software connects to it. Now the arrow points inward: a parent agent, an orchestrator script, Claude Desktop, Zed, or the OpenAI Agents SDK launches Codex and calls it as a tool to get coding work done.

Think of it like hiring. As a client, Codex is the manager hiring specialist contractors (the MCP servers). As a server, Codex is the contractor — a self-contained coding agent that some larger system hires to read a repo, make a change, run the tests, and report back. The whole point is delegation: you embed a full Codex agent inside a bigger system without re-implementing planning, editing, sandboxing, or approvals.

Keep these two directions separate in your head. They use different commands and solve opposite problems, and the names are deliberately close enough to confuse you if you're not careful.

The single most common mistake here is conflating two commands whose names differ by one hyphenated word. They are not the same family.

• codex mcp is a command group for managing the servers Codex connects to as a client. Its subcommands are add, list, get, remove, login, and logout. These edit the [mcp_servers] tables in ~/.codex/config.toml.
• codex mcp-server is a single top-level command — a sibling of codex mcp, not a subcommand of it. It runs Codex itself as a server.

From the CLI reference, codex mcp-server is described as:

Run Codex as an MCP server over stdio so that other tools can connect. This command inherits global configuration overrides and exits when the downstream client closes the connection.

Unpack that one sentence — every clause matters:

• "over stdio" — Codex speaks JSON-RPC over standard input/output. There is no port, no URL. The client launches codex mcp-server as a child process and talks to it through the process's stdin/stdout pipes.
• "other tools can connect" — any MCP-aware client (an orchestrator, an SDK, a desktop app) can be that parent.
• "inherits global configuration overrides" — flags and config you'd pass to the CLI still apply to the server process.
• "exits when the downstream client closes the connection" — the server's lifecycle is bound to the client. You don't start and stop it yourself; the client owns it. Close the client, the server process dies.

# Manage servers Codex connects TO (client role)
codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp list

# Run Codex itself AS a server (server role) — usually launched BY a client, not by hand
codex mcp-server

You will rarely type codex mcp-server directly at a prompt — there's nothing to see, because it's waiting to speak JSON-RPC to a parent, not to a human. It's the command your client config points at.

When Codex runs as a server, it advertises exactly two MCP tools to whatever client connects. That's the entire surface area — and it maps cleanly onto how a conversation works:

That's it. You begin a turn-based, multi-turn coding session by calling codex once, then drive every subsequent turn with codex-reply. The first tool opens the conversation; the second keeps it going.

Under the hood, calling codex spawns a Codex session (via ThreadManager in codex-core), streams progress to the client as MCP notifications while the turn runs, and returns the final response when the turn completes. So the client both gets live updates and a clean final answer — exactly what an orchestrator needs to show progress and then act on the result.

The mental model is a phone call. codex dials — it opens the line and you say your first thing. codex-reply is every sentence after that on the same call. The thing that ties them together — the "line" you stay on — is the threadId, which we'll get to next.

The codex tool takes a single required parameter, prompt, plus a set of optional parameters that let the calling client configure the delegated session exactly as if it were launching the CLI itself.

Two of these deserve emphasis because they're the same two independent controls you've learned throughout Codex — and they remain independent here:

• approval-policy governs when Codex asks for confirmation.
• sandbox governs where Codex is allowed to act.

They are orthogonal. A parent agent delegating an automated, unattended task will typically pair a permissive approval policy with a tight sandbox — e.g. approval-policy: never with sandbox: read-only for a code-review delegation, so Codex can read and reason but cannot touch the filesystem and never blocks waiting on a human who isn't there.

// A client's MCP tool call to start a read-only review session
{
  "tool": "codex",
  "arguments": {
    "prompt": "Review the diff on the current branch for security issues. Report findings only.",
    "approval-policy": "never",
    "sandbox": "read-only",
    "cwd": "/repos/payments-api"
  }
}

Note the kebab-case parameter names (approval-policy, base-instructions, include-plan-tool). That's the MCP tool schema; it's distinct from the snake_case keys you'd write in config.toml.

A single codex call runs one turn and returns. To have a conversation — ask a follow-up, request a fix, iterate — the client uses codex-reply, which takes two required parameters:

• prompt — the next user message.
• threadId — the identifier of the session to continue.

Where does the threadId come from? When the initial codex call completes, the tool-call response includes it in structuredContent.threadId. The client reads it from there and passes it back on every codex-reply. That single string is what makes the session stateful: it tells Codex which conversation — with its accumulated context, files read, and plan — to resume.

  client                           Codex (mcp-server)
    │  call  codex(prompt=…)            │
    │ ───────────────────────────────► │  starts session, runs turn
    │  ◄─── notifications (progress) ── │  (streamed events)
    │  ◄─── result + structuredContent  │
    │        .threadId = "abc123"       │
    │                                   │
    │  call codex-reply(                │
    │     prompt=…, threadId="abc123")  │
    │ ───────────────────────────────► │  resumes SAME session
    │  ◄─── result (+ same threadId) ── │

The pattern is always the same: codex once to open, codex-reply N times to continue, threading the same threadId through each follow-up. Lose the threadId and you can't continue that session — calling codex again starts a fresh one with no memory of the first.

// Turn 2: continue the session from the previous response
{
  "tool": "codex-reply",
  "arguments": {
    "prompt": "Now fix the highest-severity issue you found and run the tests.",
    "threadId": "abc123"   // pulled from the first call's structuredContent.threadId
  }
}

The reason to run Codex as a server is delegation inside a bigger system. Any MCP-aware host can now treat a full Codex coding agent as just another tool in its toolbox:

• A multi-agent orchestrator routes tasks to specialists: a planning agent decomposes the work, then hands each coding sub-task to Codex via the codex tool and stitches the results together.
• The OpenAI Agents SDK can launch codex mcp-server as a subprocess and call it as a tool, so an SDK-built agent gains real repo-editing, command-running, sandboxed coding ability for free — no need to rebuild planning, editing, or safety.
• Desktop / editor clients (Claude Desktop, Zed) that speak MCP can wire Codex in as a connected tool.

This is also the conceptual bridge to the SDK and multi-agent material that follows: once you understand that Codex exposes a clean, two-tool MCP interface with a threadId for continuity, the SDK integration is just a more ergonomic wrapper over exactly this protocol.

One capability worth calling out because it affects throughput: read-only MCP tools that advertise the readOnlyHint capability are allowed to run in parallel. A tool flagged readOnlyHint promises it won't mutate state, so there's no correctness risk in firing several at once. For an orchestrator fanning out read-only lookups, that hint is what unlocks concurrency instead of forcing everything to serialize. (Note: this is a property of the MCP tool layer broadly — it's the same hint Codex honors when it's the client calling read-only tools.)

# What a client's MCP config points at to embed Codex as a tool
# (the client launches this subprocess and speaks JSON-RPC to it)
command = "codex"
args    = ["mcp-server"]

And remember codex mcp-server is distinct from codex app-server --stdio, a separate, richer app-server integration surface. For the "call Codex as a tool over MCP" use case in this lesson, codex mcp-server is the one you want.