mirror of
https://github.com/openai/codex.git
synced 2026-04-28 00:25:56 +00:00
docs: refresh MCP server guide
This commit is contained in:
Thibault Sottiaux
@@ -8,28 +8,7 @@ This document describes Codex’s experimental MCP server interface: a JSON‑RP
|
||||
|
||||
## Overview
|
||||
|
||||
Codex exposes a small set of MCP‑compatible methods to create and manage conversations, send user input, receive live events, and handle approval prompts. The types are defined in `protocol/src/mcp_protocol.rs` and re‑used by the MCP server implementation in `mcp-server/`.
|
||||
|
||||
At a glance:
|
||||
|
||||
- Conversations
|
||||
- `newConversation` → start a Codex session
|
||||
- `sendUserMessage` / `sendUserTurn` → send user input into a conversation
|
||||
- `interruptConversation` → stop the current turn
|
||||
- `listConversations`, `resumeConversation`, `archiveConversation`
|
||||
- Configuration and info
|
||||
- `getUserSavedConfig`, `setDefaultModel`, `getUserAgent`, `userInfo`
|
||||
- Auth
|
||||
- `loginApiKey`, `loginChatGpt`, `cancelLoginChatGpt`, `logoutChatGpt`, `getAuthStatus`
|
||||
- Utilities
|
||||
- `gitDiffToRemote`, `execOneOffCommand`
|
||||
- Approvals (server → client requests)
|
||||
- `applyPatchApproval`, `execCommandApproval`
|
||||
- Notifications (server → client)
|
||||
- `loginChatGptComplete`, `authStatusChange`
|
||||
- `codex/event` stream with agent events
|
||||
|
||||
See code for full type definitions and exact shapes: `protocol/src/mcp_protocol.rs`.
|
||||
Codex now surfaces its functionality through standard MCP `tools/call` requests. A `tools/list` request returns the `codex` tool, which starts a session, and the `codex-reply` tool, which continues an existing session. The JSON schemas backing both tools are generated in `codex-rs/mcp-server/src/codex_tool_config.rs`. Codex continues to reuse the shared event types defined in `codex-rs/protocol/src/protocol.rs`. For clients that still speak the legacy JSON‑RPC API, its protocol definitions live in `codex-rs/app-server-protocol/src/protocol.rs`.
|
||||
|
||||
## Starting the server
|
||||
|
||||
@@ -47,78 +26,39 @@ npx @modelcontextprotocol/inspector codex mcp-server
|
||||
|
||||
Use the separate `codex mcp` subcommand to manage configured MCP server launchers in `config.toml`.
|
||||
|
||||
## Conversations
|
||||
## Codex tools
|
||||
|
||||
Start a new session with optional overrides:
|
||||
Send `tools/list` to discover the available tools:
|
||||
|
||||
Request `newConversation` params (subset):
|
||||
- `codex`: starts a new Codex session. The request `arguments` accept the fields surfaced by `CodexToolCallParam`, including the required `prompt` plus optional `model`, `profile`, `cwd`, `approval-policy`, `sandbox`, `config`, `base-instructions`, and `include-plan-tool` overrides. When the tool call finishes, the server resolves the `tools/call` request with the model’s final message in the response `content`.
|
||||
- `codex-reply`: continues an existing session. The request `arguments` must include `conversationId` and `prompt`, matching the `CodexToolCallReplyParam` schema. Use the `conversationId` returned in earlier events to correlate with the active session.
|
||||
|
||||
- `model`: string model id (e.g. "o3", "gpt-5", "gpt-5-codex")
|
||||
- `profile`: optional named profile
|
||||
- `cwd`: optional working directory
|
||||
- `approvalPolicy`: `untrusted` | `on-request` | `on-failure` | `never`
|
||||
- `sandbox`: `read-only` | `workspace-write` | `danger-full-access`
|
||||
- `config`: map of additional config overrides
|
||||
- `baseInstructions`: optional instruction override
|
||||
- `includePlanTool` / `includeApplyPatchTool`: booleans
|
||||
|
||||
Response: `{ conversationId, model, reasoningEffort?, rolloutPath }`
|
||||
|
||||
Send input to the active turn:
|
||||
|
||||
- `sendUserMessage` → enqueue items to the conversation
|
||||
- `sendUserTurn` → structured turn with explicit `cwd`, `approvalPolicy`, `sandboxPolicy`, `model`, optional `effort`, and `summary`
|
||||
|
||||
Interrupt a running turn: `interruptConversation`.
|
||||
|
||||
List/resume/archive: `listConversations`, `resumeConversation`, `archiveConversation`.
|
||||
Both tools run asynchronously. While a tool call is in flight, Codex streams progress via MCP notifications so the client can render intermediate output or handle approvals.
|
||||
|
||||
## Event stream
|
||||
|
||||
While a conversation runs, the server sends notifications:
|
||||
|
||||
- `codex/event` with the serialized Codex event payload. The shape matches `core/src/protocol.rs`’s `Event` and `EventMsg` types. Some notifications include a `_meta.requestId` to correlate with the originating request.
|
||||
- Auth notifications via method names `loginChatGptComplete` and `authStatusChange`.
|
||||
|
||||
Clients should render events and, when present, surface approval requests (see next section).
|
||||
While a conversation runs, the server sends JSON‑RPC notifications whose `method` is `codex/event`. The payload embeds the serialized `Event`/`EventMsg` structures from `codex-rs/protocol/src/protocol.rs`. Notifications include `_meta.requestId` so clients can associate each event with the originating `tools/call`.
|
||||
|
||||
## Approvals (server → client)
|
||||
|
||||
When Codex needs approval to apply changes or run commands, the server issues JSON‑RPC requests to the client:
|
||||
When Codex needs approval to apply a patch or run a command, it issues an MCP elicitation request (`ElicitRequest`). Patch prompts carry `PatchApprovalElicitRequestParams` and command prompts use `ExecApprovalElicitRequestParams`. Respond with JSON that includes a `decision` field whose value is one of the `ReviewDecision` strings: `approved`, `approved_for_session`, `denied`, or `abort`. These map directly to the enum defined in `codex-rs/protocol/src/protocol.rs` and determine whether Codex proceeds, auto‑approves similar actions for the current session, or halts work.
|
||||
|
||||
- `applyPatchApproval { conversationId, callId, fileChanges, reason?, grantRoot? }`
|
||||
- `execCommandApproval { conversationId, callId, command, cwd, reason? }`
|
||||
## Example workflow
|
||||
|
||||
The client must reply with `{ decision: "allow" | "deny" }` for each request.
|
||||
|
||||
## Auth helpers
|
||||
|
||||
For ChatGPT or API‑key based auth flows, the server exposes helpers:
|
||||
|
||||
- `loginApiKey { apiKey }`
|
||||
- `loginChatGpt` → returns `{ loginId, authUrl }`; browser completes flow; then `loginChatGptComplete` notification follows
|
||||
- `cancelLoginChatGpt { loginId }`, `logoutChatGpt`, `getAuthStatus { includeToken?, refreshToken? }`
|
||||
|
||||
## Example: start and send a message
|
||||
Start a session with the `codex` tool:
|
||||
|
||||
```json
|
||||
{ "jsonrpc": "2.0", "id": 1, "method": "newConversation", "params": { "model": "gpt-5", "approvalPolicy": "on-request" } }
|
||||
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "codex", "arguments": { "prompt": "List the files in this repo.", "approval-policy": "on-request", "sandbox": "workspace-write" } } }
|
||||
```
|
||||
|
||||
Server responds:
|
||||
The server streams `codex/event` notifications as the session runs. When the task completes, the `tools/call` response resolves with the final assistant message in its `content`. To keep going, call `codex-reply` with the returned `conversationId`:
|
||||
|
||||
```json
|
||||
{ "jsonrpc": "2.0", "id": 1, "result": { "conversationId": "c7b0…", "model": "gpt-5", "rolloutPath": "/path/to/rollout.jsonl" } }
|
||||
{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "codex-reply", "arguments": { "conversationId": "c7b0…", "prompt": "Great, please open README.md." } } }
|
||||
```
|
||||
|
||||
Then send input:
|
||||
|
||||
```json
|
||||
{ "jsonrpc": "2.0", "id": 2, "method": "sendUserMessage", "params": { "conversationId": "c7b0…", "items": [{ "type": "text", "text": "Hello Codex" }] } }
|
||||
```
|
||||
|
||||
While processing, the server emits `codex/event` notifications containing agent output, approvals, and status updates.
|
||||
Any approval prompts during either call arrive as elicitation requests. Reply with the desired `ReviewDecision` to allow, deny, or pause execution.
|
||||
|
||||
## Compatibility and stability
|
||||
|
||||
This interface is experimental. Method names, fields, and event shapes may evolve. For the authoritative schema, consult `protocol/src/mcp_protocol.rs` and the corresponding server wiring in `mcp-server/`.
|
||||
This interface is experimental. Tool schemas, fields, and event shapes may evolve. For the authoritative definitions, consult `codex-rs/mcp-server/src/codex_tool_config.rs`, the shared event types in `codex-rs/protocol/src/protocol.rs`, and the legacy JSON‑RPC spec in `codex-rs/app-server-protocol/src/protocol.rs`.
|
||||
|
||||
Reference in New Issue
Block a user