feat: add conversationId to MCP server messages

2026-10-31 19:28:49 +00:00 · 2026-01-13 21:58:33 -08:00
parent 31d9b6f4d2
commit 0499d0cf7a
8 changed files with 337 additions and 90 deletions
@@ -0,0 +1,67 @@
+## 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](https://platform.openai.com/docs/guides/agents). 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](https://modelcontextprotocol.io/legacy/tools/inspector):
+
+```bash
+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](https://github.com/openai/codex/blob/main/docs/config.md#config) 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:
+
+```json
+{
+  "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:
+
+```json
+{
+  "_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.