4.3 KiB
Using Codex as an MCP Server
The Codex CLI can also be run as an MCP server via codex mcp-server. For example, you can use codex mcp-server to make Codex available as a tool inside of a multi-agent framework like the OpenAI Agents SDK. Use codex mcp separately to add/list/get/remove MCP server launchers in your configuration.
Codex MCP Server Quickstart
You can launch a Codex MCP server with the Model Context Protocol Inspector:
npx @modelcontextprotocol/inspector codex mcp-server
Send a tools/list request and you will see that there are two tools available:
codex - Run a Codex session. Accepts configuration parameters matching the Codex Config struct. The codex tool takes the following properties:
| Property | Type | Description |
|---|---|---|
prompt (required) |
string | The initial user prompt to start the Codex conversation. |
approval-policy |
string | Approval policy for shell commands generated by the model: untrusted, on-failure, on-request, never. |
base-instructions |
string | The set of instructions to use instead of the default ones. |
config |
object | Individual config settings that will override what is in $CODEX_HOME/config.toml. |
cwd |
string | Working directory for the session. If relative, resolved against the server process's current directory. |
model |
string | Optional override for the model name (e.g. o3, o4-mini). |
profile |
string | Configuration profile from config.toml to specify default options. |
sandbox |
string | Sandbox mode: read-only, workspace-write, or danger-full-access. |
The tools/call response for codex includes the thread id in structuredContent so the client can resume the session later:
{
"content": [{ "type": "text", "text": "..." }],
"structuredContent": { "threadId": "..." }
}
While the tool is running, codex/event notifications include _meta.threadId so clients can correlate events to a conversation:
{
"_meta": { "requestId": 1, "threadId": "..." },
"id": "evt-...",
"msg": { "type": "..." }
}
codex-reply - Continue a Codex session by providing the thread id and prompt. The codex-reply tool takes the following properties:
| Property | Type | Description |
|---|---|---|
prompt (required) |
string | The next user prompt to continue the Codex conversation. |
threadId (required) |
string | The id of the conversation to continue. |
Trying it Out
Tip
Codex often takes a few minutes to run. To accommodate this, adjust the MCP inspector's Request and Total timeouts to 600000ms (10 minutes) under ⛭ Configuration.
Use the MCP inspector and codex mcp-server to build a simple tic-tac-toe game with the following settings:
approval-policy: never
prompt: Implement a simple tic-tac-toe game with HTML, JavaScript, and CSS. Write the game in a single file called index.html.
sandbox: workspace-write
Click "Run Tool" and you should see a list of events emitted from the Codex MCP server as it builds the game.