Codex Discussion MCP
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | CLI option --cwd: default working directory used when discussion_start.cwd is omitted. Recommended to pass an absolute project path. | |
| codex-arg | No | CLI option --codex-arg: repeatable argument that replaces the default app-server launch arguments. Values starting with '-' must be joined with '='. | |
| codex-command | No | CLI option --codex-command: absolute path to the Codex executable, overriding CODEX_DISCUSSION_CODEX_PATH. | |
| CODEX_DISCUSSION_CODEX_PATH | No | Absolute path to the Codex executable. Used when --codex-command is not provided; otherwise falls back to `codex` on PATH. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Discuss with Codex as an independent coding partner. First call models_list to discover models and supported effort levels. Choose model and effort based on complexity. discussion_start/reply return immediately; call discussion_read repeatedly until a terminal status. Supply all context Codex needs; your own conversation is not shared automatically. Use an absolute cwd for the project. Codex discussions are read-only.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| models_listA | Call first to fetch the current Codex model catalog with descriptions, default model, default effort and supported effort descriptions. No inference is run. Catalog entries do not guarantee account/provider inference access. Includes package update status; relay an available update once per newer version per session in the user language. Updating and reconnecting are user actions. |
| discussion_startA | Start an independent read-only Codex conversation. Call models_list first, then select model and effort for the question complexity. Supply the question, relevant context and optional absolute project cwd. Returns discussionId and turnId immediately; read output using discussion_read. |
| discussion_replyA | Send a follow-up, objection or additional evidence to an existing discussion. Finish or cancel the active turn first. Model and effort can change on each reply. Omitted choices inherit; changing model without effort uses the new model default. Returns immediately; use discussion_read. |
| discussion_readA | Read the latest or specified turn. Poll with waitMs up to 20000 until completed, failed, interrupted or connectionLost; new output can return before completion. Follow nextCursor for more message chunks. During generation, read again without a cursor for updated text. Persisted historical per-turn model/effort may be unavailable; threadDefaults are reported separately. |
| discussion_cancelA | Request interruption of exactly the specified turn. An accepted cancellation request is distinct from the final interrupted status; confirm with discussion_read. Completed older turns are returned without interrupting newer work. |
| discussion_forgetA | Explicitly release inactive discussion output retained in this MCP process. Does not delete saved Codex history, cancel generation, or run inference. Rejects active, pending, loading, or uncertain connection-lost work. Returns forgotten=false for an unknown or already released local discussion. Old cursors become invalid; read without a cursor to resume saved history while connected. Received output otherwise remains retained until process exit. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 6 tools
Each tool maps to a distinct action in the discussion lifecycle: start, reply, read, cancel, forget, and model catalog lookup. The potentially confusing pair, cancel and forget, is explicitly differentiated by interrupting a turn versus releasing local output.
All names use snake_case with a consistent entity_action pattern: discussion_start, discussion_read, discussion_reply, discussion_cancel, discussion_forget, and models_list. The model catalog tool differs only in entity name, which reflects its distinct scope.
Six tools is a well-scoped set for managing Codex discussion turns plus fetching the model catalog. Every tool has a clear lifecycle role, with no redundant or filler tools.
The surface covers the core lifecycle: model discovery, starting a discussion, replying, reading output, canceling a turn, and forgetting local output. Minor gaps include no explicit tool to list existing discussions or to inspect saved history outside a known discussion/turn, but agents can work around this by tracking IDs.