mirror of
https://github.com/openai/codex.git
synced 2026-04-29 00:55:38 +00:00
chore(app-server): delete v1 RPC methods and notifications (#13375)
## Summary This removes the old app-server v1 methods and notifications we no longer need, while keeping the small set the main codex app client still depends on for now. The remaining legacy surface is: - `initialize` - `getConversationSummary` - `getAuthStatus` - `gitDiffToRemote` - `fuzzyFileSearch` - `fuzzyFileSearch/sessionStart` - `fuzzyFileSearch/sessionUpdate` - `fuzzyFileSearch/sessionStop` And the raw `codex/event/*` notifications emitted from core. These notifications will be removed in a followup PR. ## What changed - removed deprecated v1 request variants from the protocol and app-server dispatcher - removed deprecated typed notifications: `authStatusChange`, `loginChatGptComplete`, and `sessionConfigured` - updated the app-server test client to use v2 flows instead of deleted v1 flows - deleted legacy-only app-server test suites and added focused coverage for `getConversationSummary` - regenerated app-server schema fixtures and updated the MCP interface docs to match the remaining compatibility surface ## Testing - `just write-app-server-schema` - `cargo test -p codex-app-server-protocol` - `cargo test -p codex-app-server`
This commit is contained in:
Owen Lin
@@ -1,38 +1,36 @@
|
||||
# Codex MCP Server Interface [experimental]
|
||||
|
||||
This document describes Codex’s experimental MCP server interface: a JSON‑RPC API that runs over the Model Context Protocol (MCP) transport to control a local Codex engine.
|
||||
This document describes Codex's experimental MCP server interface: a JSON-RPC API that runs over the Model Context Protocol (MCP) transport to control a local Codex engine.
|
||||
|
||||
- Status: experimental and subject to change without notice
|
||||
- Server binary: `codex mcp-server` (or `codex-mcp-server`)
|
||||
- Transport: standard MCP over stdio (JSON‑RPC 2.0, line‑delimited)
|
||||
- Transport: standard MCP over stdio (JSON-RPC 2.0, line-delimited)
|
||||
|
||||
## 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/`.
|
||||
Codex exposes MCP-compatible methods to manage threads, turns, accounts, config, and approvals. The types live in `app-server-protocol/src/protocol/{common,v1,v2}.rs` and are consumed by the app server implementation in `app-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`
|
||||
- `model/list` → enumerate available models and reasoning options
|
||||
- `collaborationMode/list` → enumerate collaboration mode presets (experimental)
|
||||
- Auth
|
||||
- Primary v2 RPCs
|
||||
- `thread/start`, `thread/resume`, `thread/fork`, `thread/read`, `thread/list`
|
||||
- `turn/start`, `turn/steer`, `turn/interrupt`
|
||||
- `account/read`, `account/login/start`, `account/login/cancel`, `account/logout`, `account/rateLimits/read`
|
||||
- notifications: `account/login/completed`, `account/updated`, `account/rateLimits/updated`
|
||||
- Utilities
|
||||
- `gitDiffToRemote`, `execOneOffCommand`
|
||||
- Approvals (server → client requests)
|
||||
- `config/read`, `config/value/write`, `config/batchWrite`
|
||||
- `model/list`, `app/list`, `collaborationMode/list`
|
||||
- Remaining v1 compatibility RPCs
|
||||
- `getConversationSummary`
|
||||
- `getAuthStatus`
|
||||
- `gitDiffToRemote`
|
||||
- `fuzzyFileSearch`, `fuzzyFileSearch/sessionStart`, `fuzzyFileSearch/sessionUpdate`, `fuzzyFileSearch/sessionStop`
|
||||
- Notifications
|
||||
- v2 typed notifications such as `thread/started`, `turn/completed`, `account/login/completed`
|
||||
- `codex/event/*` stream notifications for live agent events
|
||||
- `fuzzyFileSearch/sessionUpdated`, `fuzzyFileSearch/sessionCompleted`
|
||||
- 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`.
|
||||
See code for full type definitions and exact shapes: `app-server-protocol/src/protocol/{common,v1,v2}.rs`.
|
||||
|
||||
## Starting the server
|
||||
|
||||
@@ -50,73 +48,45 @@ npx @modelcontextprotocol/inspector codex mcp-server
|
||||
|
||||
Use the separate `codex mcp` subcommand to manage configured MCP server launchers in `config.toml`.
|
||||
|
||||
## Conversations
|
||||
## Threads and turns
|
||||
|
||||
Start a new session with optional overrides:
|
||||
Use the v2 thread and turn APIs for all new integrations. `thread/start` creates a thread, `turn/start` submits user input, `turn/interrupt` stops an in-flight turn, and `thread/list` / `thread/read` expose persisted history.
|
||||
|
||||
Request `newConversation` params (subset):
|
||||
`getConversationSummary` remains as a compatibility helper for clients that still need a summary lookup by `conversationId` or `rolloutPath`.
|
||||
|
||||
- `model`: string model id (e.g. "o3", "gpt-5.1", "gpt-5.1-codex")
|
||||
- `profile`: optional named profile
|
||||
- `cwd`: optional working directory
|
||||
- `approvalPolicy`: `untrusted` | `on-request` | `on-failure` (deprecated) | `never`
|
||||
- `sandbox`: `read-only` | `workspace-write` | `external-sandbox` (honors `networkAccess` restricted/enabled) | `danger-full-access`
|
||||
- `config`: map of additional config overrides
|
||||
- `baseInstructions`: optional instruction override
|
||||
- `compactPrompt`: optional replacement for the default compaction prompt
|
||||
- `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`, `summary`, optional `personality`, and optional `outputSchema` (JSON Schema for the final assistant message)
|
||||
|
||||
Valid `personality` values are `friendly`, `pragmatic`, and `none`. When `none` is selected, the personality placeholder is replaced with an empty string.
|
||||
|
||||
For v2 threads, `turn/start` also accepts `outputSchema` to constrain the final assistant message for that turn.
|
||||
|
||||
Interrupt a running turn: `interruptConversation`.
|
||||
|
||||
List/resume/archive: `listConversations`, `resumeConversation`, `archiveConversation`.
|
||||
|
||||
For v2 threads, use `thread/list` with filters such as `archived: true`, `cwd: "/path"`, or
|
||||
`searchTerm: "needle"` to
|
||||
narrow results, and `thread/unarchive` to restore archived rollouts to the active sessions
|
||||
directory (it returns the restored thread summary).
|
||||
For complete request and response shapes, see the app-server README and the protocol definitions in `app-server-protocol/src/protocol/v2.rs`.
|
||||
|
||||
## Models
|
||||
|
||||
Fetch the catalog of models available in the current Codex build with `model/list`. The request accepts optional pagination inputs:
|
||||
|
||||
- `limit` – number of models to return (defaults to a server-selected value)
|
||||
- `cursor` – opaque string from the previous response’s `nextCursor`
|
||||
- `limit` - number of models to return (defaults to a server-selected value)
|
||||
- `cursor` - opaque string from the previous response's `nextCursor`
|
||||
|
||||
Each response yields:
|
||||
|
||||
- `data` – ordered list of models. A model includes:
|
||||
- `data` - ordered list of models. A model includes:
|
||||
- `id`, `model`, `displayName`, `description`
|
||||
- `supportedReasoningEfforts` – array of objects with:
|
||||
- `reasoningEffort` – one of `none|minimal|low|medium|high|xhigh`
|
||||
- `description` – human-friendly label for the effort
|
||||
- `defaultReasoningEffort` – suggested effort for the UI
|
||||
- `inputModalities` – accepted input types for the model
|
||||
- `supportsPersonality` – whether the model supports personality-specific instructions
|
||||
- `isDefault` – whether the model is recommended for most users
|
||||
- `upgrade` – optional recommended upgrade model id
|
||||
- `upgradeInfo` – optional upgrade metadata object with:
|
||||
- `model` – recommended upgrade model id
|
||||
- `upgradeCopy` – optional display copy for the upgrade recommendation
|
||||
- `modelLink` – optional link for the upgrade recommendation
|
||||
- `migrationMarkdown` – optional markdown shown when presenting the upgrade
|
||||
- `nextCursor` – pass into the next request to continue paging (optional)
|
||||
- `supportedReasoningEfforts` - array of objects with:
|
||||
- `reasoningEffort` - one of `none|minimal|low|medium|high|xhigh`
|
||||
- `description` - human-friendly label for the effort
|
||||
- `defaultReasoningEffort` - suggested effort for the UI
|
||||
- `inputModalities` - accepted input types for the model
|
||||
- `supportsPersonality` - whether the model supports personality-specific instructions
|
||||
- `isDefault` - whether the model is recommended for most users
|
||||
- `upgrade` - optional recommended upgrade model id
|
||||
- `upgradeInfo` - optional upgrade metadata object with:
|
||||
- `model` - recommended upgrade model id
|
||||
- `upgradeCopy` - optional display copy for the upgrade recommendation
|
||||
- `modelLink` - optional link for the upgrade recommendation
|
||||
- `migrationMarkdown` - optional markdown shown when presenting the upgrade
|
||||
- `nextCursor` - pass into the next request to continue paging (optional)
|
||||
|
||||
## Collaboration modes (experimental)
|
||||
|
||||
Fetch the built-in collaboration mode presets with `collaborationMode/list`. This endpoint does not accept pagination and returns the full list in one response:
|
||||
|
||||
- `data` – ordered list of collaboration mode masks (partial settings to apply on top of the base mode)
|
||||
- `data` - ordered list of collaboration mode masks (partial settings to apply on top of the base mode)
|
||||
- For tri-state fields like `reasoning_effort` and `developer_instructions`, omit the field to keep the current value, set it to `null` to clear it, or set a concrete value to update it.
|
||||
|
||||
When sending `turn/start` with `collaborationMode`, `settings.developer_instructions: null` means "use built-in instructions for the selected mode".
|
||||
@@ -125,16 +95,14 @@ When sending `turn/start` with `collaborationMode`, `settings.developer_instruct
|
||||
|
||||
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`.
|
||||
- `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.
|
||||
- `fuzzyFileSearch/sessionUpdated` and `fuzzyFileSearch/sessionCompleted` for the legacy fuzzy search flow.
|
||||
|
||||
Clients should render events and, when present, surface approval requests (see next section).
|
||||
|
||||
## Tool responses
|
||||
|
||||
The `codex` and `codex-reply` tools return standard MCP `CallToolResult` payloads. For
|
||||
compatibility with MCP clients that prefer `structuredContent`, Codex mirrors the
|
||||
content blocks inside `structuredContent` alongside the `threadId`.
|
||||
The `codex` and `codex-reply` tools return standard MCP `CallToolResult` payloads. For compatibility with MCP clients that prefer `structuredContent`, Codex mirrors the content blocks inside `structuredContent` alongside the `threadId`.
|
||||
|
||||
Example:
|
||||
|
||||
@@ -148,9 +116,9 @@ Example:
|
||||
}
|
||||
```
|
||||
|
||||
## Approvals (server → client)
|
||||
## 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 changes or run commands, the server issues JSON-RPC requests to the client:
|
||||
|
||||
- `applyPatchApproval { conversationId, callId, fileChanges, reason?, grantRoot? }`
|
||||
- `execCommandApproval { conversationId, callId, approvalId?, command, cwd, reason? }`
|
||||
@@ -159,28 +127,17 @@ The client must reply with `{ decision: "allow" | "deny" }` for each request.
|
||||
|
||||
## Auth helpers
|
||||
|
||||
For the complete request/response shapes and flow examples, see the [“Auth endpoints (v2)” section in the app‑server README](../app-server/README.md#auth-endpoints-v2).
|
||||
For the complete request/response shapes and flow examples, see the [Auth endpoints (v2) section in the app-server README](../app-server/README.md#auth-endpoints-v2).
|
||||
|
||||
## Example: start and send a message
|
||||
## Legacy compatibility methods
|
||||
|
||||
```json
|
||||
{ "jsonrpc": "2.0", "id": 1, "method": "newConversation", "params": { "model": "gpt-5.1", "approvalPolicy": "on-request" } }
|
||||
```
|
||||
The server still accepts a narrow v1 compatibility surface for existing app clients:
|
||||
|
||||
Server responds:
|
||||
|
||||
```json
|
||||
{ "jsonrpc": "2.0", "id": 1, "result": { "conversationId": "c7b0…", "model": "gpt-5.1", "rolloutPath": "/path/to/rollout.jsonl" } }
|
||||
```
|
||||
|
||||
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.
|
||||
- `getConversationSummary`
|
||||
- `getAuthStatus`
|
||||
- `gitDiffToRemote`
|
||||
- `fuzzyFileSearch`, `fuzzyFileSearch/sessionStart`, `fuzzyFileSearch/sessionUpdate`, `fuzzyFileSearch/sessionStop`
|
||||
|
||||
## 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. Method names, fields, and event shapes may evolve. For the authoritative schema, consult `app-server-protocol/src/protocol/{common,v1,v2}.rs` and the corresponding server wiring in `app-server/`.
|
||||
|
||||
Reference in New Issue
Block a user