Codex Discussion MCP
Query Codex models and run asynchronous, multi-turn, read-only discussions with Codex as an independent review partner.
List available Codex models, descriptions, defaults, and supported reasoning effort levels, plus package update status.
Start a new Codex discussion in an optional absolute project directory, choosing model and effort.
Continue an existing discussion with follow-ups, counterarguments, or additional evidence, optionally changing model/effort.
Poll/read discussion output asynchronously, including paginated message chunks, statuses, and errors.
Interrupt a specific running turn.
Release locally retained output for an inactive discussion without deleting Codex’s saved history.
Resume saved discussions by conversation ID across later sessions/processes when Codex storage is available.
Invokes the OpenAI Codex CLI as an independent discussion partner, letting an agent query the available Codex models and reasoning efforts, start and resume multi-turn discussions (threads) with maintained context, poll or wait for long-running responses, and cancel individual turns — using the existing Codex CLI login and provider configuration.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Codex Discussion MCP Review my auth design and debate the tradeoffs with me"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Codex Discussion MCP
A local MCP server that lets Claude Code, Antigravity CLI, Kiro CLI, and other agents call Codex as an independent discussion partner. The calling agent leads the discussion and can choose a model and reasoning effort for each question.
Query Codex for available models, descriptions, and supported effort levels
Send questions, counterarguments, and additional evidence while retaining context
Retrieve long-running responses asynchronously and interrupt a specific turn
Resume in a later session using a conversation ID saved by Codex
Explore projects with read-only access and exchange public messages
Skill user manual · Agent skill
The package name is @mirolab/codex-discussion-mcp. Install the version published
to npm with the commands below. To use an unpublished version, install the .tgz
from the npm-package artifact in GitHub Actions or build it locally.
Publishing guide
Requirements
Node.js 22.14 or later and npm
Codex CLI installed and signed in
Validated against the app-server protocol in Codex CLI 0.166.0
The server uses your existing Codex CLI login and model provider settings. You do not need to enter a separate OpenAI API key for the MCP server. Your provider's account permissions and usage limits still apply.
Codex has read-only access when exploring projects. Inherited MCP connections and plugins are disabled in the child process used for discussions. The calling agent's conversation is not shared automatically, so include the code, explanations, and assumptions needed for each question.
Related MCP server: Claude Code Bridge
Installation
Install the published package globally:
npm install -g @mirolab/codex-discussion-mcp
codex-discussion-mcp --helpYou can also run it without a global installation. Register this command in your MCP configuration:
npx -y @mirolab/codex-discussion-mcp@0.1.5This command waits for requests as a stdio MCP server. You do not type questions into it like a terminal chat command; the MCP host connects to the server and calls its tools.
Version checks and updates
The server checks the public npm latest metadata for this package automatically
in the background at startup. models_list returns an additive update object
in both structured results and the JSON text used by legacy hosts. Its status is
available, current (the checked stable version is no newer than the running
version), unavailable, or disabled. An available update includes
currentVersion, latestVersion, releaseNotesUrl, and a notice with update and
reconnect instructions. Failed checks are unavailable, never proof that your
installation is current. Model catalog metadata, including accessVerified: false, keeps its existing meaning.
Checks fetch version metadata only, with a 1500 ms network deadline covering
headers and body, and coalesce concurrent requests within one MCP process.
Successful and failed checks are cached for 24 hours, including across
process restarts. Only version/check metadata is saved in
codex-discussion-mcp/update.json under the user's cache directory:
Linux:
$XDG_CACHE_HOME, if absolute; otherwise~/.cache.macOS:
~/Library/Caches.Windows:
%LOCALAPPDATA%, otherwise~/AppData/Local.
Cache errors are ignored; an in-memory cache still prevents repeated lookups in
that process. Startup and discussion submission, polling and cancellation do not
wait for npm. models_list waits for the bounded check alongside Codex discovery.
Offline or malformed registry responses do not prevent use of the tools.
--help and --version never request npm metadata.
To disable checks, add --no-update-check to the server's arguments or set
CODEX_DISCUSSION_UPDATE_CHECK=0 in its environment. Either disables both network
checks and update cache reads/writes. For example:
{ "command": "codex-discussion-mcp", "args": ["--no-update-check"] }The portable skill relays an available-update notice in the user's language once per newer version per session. Delivery uses tool results and agent instructions; desktop popups and display by every host are not guaranteed.
Choose the update procedure for the installation the MCP host actually uses:
Installation | User action |
Global npm installation | Run |
Project-local npm installation | In the installation's project, run |
Version-pinned | Change the configured |
After updating, reconnect/restart the MCP server through the host so it loads the new package. The server never installs code or dependencies, rewrites MCP configuration, restarts itself, runs inference for checks, or interrupts an active discussion. Finish active work before reconnecting. Separately copied skills must be refreshed separately; updating npm does not overwrite the copy or its customizations. See changelog and release notes.
Register with Claude Code
After installing globally, register it for all projects:
claude mcp add --transport stdio --scope user codex-discussion -- codex-discussion-mcp
claude mcp get codex-discussionRegister without a global installation:
claude mcp add --transport stdio --scope user codex-discussion -- \
npx -y @mirolab/codex-discussion-mcp@0.1.5To share the configuration at the project level, replace --scope user with
--scope project. You can also check the connection in Claude Code using /mcp.
Register with Kiro CLI or Antigravity CLI
Merge the server entry below into the existing mcpServers in the relevant
configuration file.
Host | User-wide configuration | Project configuration |
Kiro CLI |
|
|
Antigravity CLI |
|
|
{
"mcpServers": {
"codex-discussion": {
"command": "npx",
"args": ["-y", "@mirolab/codex-discussion-mcp@0.1.5"]
}
}
}If you installed the package globally, you can use this server entry instead:
{ "command": "codex-discussion-mcp", "args": [] }Host configuration formats may vary by installed version. See the official Claude Code documentation, Kiro documentation, and Antigravity documentation.
Project path and Codex executable
We recommend passing the project's absolute path as discussion_start.cwd.
If omitted, the server uses --cwd, falling back to the MCP process's working
directory. The host may start the MCP process outside your project.
{
"command": "codex-discussion-mcp",
"args": ["--cwd", "/absolute/path/to/project", "--codex-command", "/absolute/path/to/codex"]
}By default, --codex-command uses the CODEX_DISCUSSION_CODEX_PATH environment
variable, then codex on PATH. For advanced setups, repeat --codex-arg to replace
the default app-server launch arguments. Use = for values beginning with -,
such as --codex-arg=--some-option.
To create a transport token and launch a separate Codex app-server host, use the remote app-server setup script and guide. The MCP package's connection currently remains local stdio.
Ask your agent
For a reusable user guide, install the optional Codex Discussion skill using the skill user manual.
First, query codex-discussion for the available models and supported effort levels. Choose a model and effort suited to the question's complexity, and discuss the strengths and weaknesses of the current design with Codex. Exchange counterarguments, then summarize the points of agreement and remaining differences.
To require discussions in specific situations, add instructions like these to each agent's project guidelines:
Before major architecture decisions, get an independent review through codex-discussion. Query models_list first, then choose a model and supported effort suited to the question. Share your position and evidence, consider counterarguments, and explain the reasons for the final decision.
User guide skill
The optional codex-discussion skill guides agents through connection checks,
question preparation, model selection, complete response retrieval, and
counterarguments. Register the MCP server separately, then run this from the
project where you want to use the skill and select your coding agents:
npx skills add smallmiro/codex-discussion-mcp --skill codex-discussionFor a global installation across your local projects, add -g:
npx skills add smallmiro/codex-discussion-mcp --skill codex-discussion -gInstalling the skill does not install or register the MCP server. In Claude
Code, invoke /codex-discussion with your question; in Codex, mention
$codex-discussion.
See the skill installation and usage guide
for manual installation, supported hosts, example prompts, updates/removal, and
troubleshooting. When copying manually, include the complete skill directory
and its references/ files. The skill and manual are included in the npm package
starting with 0.1.2; published 0.1.0 and 0.1.1 do not contain them.
MCP tools
Tool | Input | Result |
|
| Model and effort catalog, retrieval time, package update status |
|
| New |
|
| New turn in the same conversation |
|
| Release inactive local output; preserve saved history |
|
| Status, public messages, |
|
| Status of the interruption request for a specific turn |
Do not hardcode model IDs or effort levels. Each entry returned by models_list
includes model, displayName, description, isDefault,
defaultReasoningEffort, and supportedReasoningEfforts. Select using the
model value, not the picker ID, id. Catalog retrieval does not verify
inference access and reports accessVerified: false.
Selection rules:
If omitted on the first question, use the catalog's default model and that model's default effort.
If omitted on a follow-up question, inherit the current persisted thread defaults, including settings from completed work in another connection. A prior read is not required.
If the model changes and effort is omitted, use the new model's default effort.
Unsupported combinations return an error that includes the allowed values.
discussion_start and discussion_reply do not wait for generation to finish.
Call the tools in this order:
models_list({})
discussion_start({message: "Review the design", cwd: "/absolute/project", model: retrieved_model, effort: supported_effort})
discussion_read({discussionId: returned_ID, waitMs: 20000})
… read again if the status is inProgress …
discussion_reply({discussionId: same_ID, message: "What do you think of this counterexample?"})waitMs accepts 0–20000, and limit accepts 1–100. A read may return before
completion when new output becomes available. Statuses are inProgress,
completed, failed, interrupted, and connectionLost. Only completed
indicates successful completion.
Use nextCursor to paginate messages. Long messages are split into chunks with
the same ID and a textOffset. Each chunk contains at most 8000 characters, and
each response at most 64000 characters. To retrieve revised text during
generation, read again without a cursor. Cursors are tied to a specific process,
conversation, and turn. After restarting the MCP server, omit the cursor and
read again.
Conversation IDs are Codex thread IDs. A later process using the same Codex
storage can resume them. When a saved turn's model or effort cannot be determined,
it is returned as null; the conversation's currently saved defaults are shown
separately in threadDefaults. If no saved effort is available, follow-up
questions require an explicit effort.
Each conversation processes one turn at a time. Additional questions while a turn
is running return DISCUSSION_BUSY. Different conversations can run
independently. Concurrently modifying the same conversation from multiple MCP
processes is unsupported. Inference is not automatically retried after a
connection closes or a request times out.
Received output stays in memory until process exit or an explicit
discussion_forget({ discussionId }) call. This releases all locally retained
turns, fetched history pages, and cursors for an inactive discussion, while
preserving Codex's saved history. There is no automatic eviction. The result is
{ discussionId, forgotten: true }, or forgotten: false if the discussion is
unknown locally or already released; unknown IDs are not loaded.
Release returns DISCUSSION_BUSY while a turn, submission, resume, read, poll,
cancellation, or another release is pending. While connected, backend inactivity
must also be confirmed. A connectionLost turn has an uncertain backend outcome
and cannot be released; completed, failed, or interrupted output can be released
after disconnect. A submission that lost its response before any terminal event,
or observed external activity without confirmed inactivity, also remains
protected after disconnect. Release never cancels or replays inference.
Old cursors return INVALID_CURSOR after release. A cursorless read can resume
saved history while connected without inference. After disconnect, released
output cannot be recovered in that MCP process; start a new process to access
saved history. Previously fetched history remains readable until release, and
unfetched source pages still require a connection.
Roadmap
Add support for connecting to a remote Codex app-server, alongside the currently supported local Codex connection. Remote connections are planned and are not yet implemented.
Development and validation
See AGENTS.md for the repository map, behavioral contracts, validation commands, and release guidance for coding agents.
npm ci
npm run check
npm run verify:package
npm run smoke -- --models-onlyverify:package installs the tarball with production dependencies only in a
separate temporary directory, checks the installed user skill and manual against
the checkout, then uses the installed command to simulate MCP discovery and a
two-turn discussion. Automated tests do not consume actual model usage.
To validate a short two-turn discussion with a signed-in Codex instance:
npm run smoke -- --inferenceThis command runs real inference and consumes account usage. CI runs type checks, tests, builds, and installation validation on Node.js 22 and 24 without real inference. The primary validation platforms are currently macOS and GitHub-hosted Ubuntu.
Publishing and design
GitHub builds and npm publishing · Design · Development plan
License
Available Tools
6 toolsdiscussion_cancelInterrupt a Codex turnAIdempotent
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.
Inputs: turnId (required), discussionId (required).
discussion_forgetForget retained local discussion outputAIdempotent
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.
Inputs: discussionId (required).
discussion_readRead Codex output or wait for progressARead-onlyIdempotent
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.
Inputs: discussionId (required), limit, cursor, turnId, +1 more.
discussion_replyContinue a Codex discussionA
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.
Inputs: message (required), discussionId (required), model, effort.
discussion_startStart a discussion with CodexA
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.
Inputs: message (required), cwd, model, effort.
models_listDiscover Codex models and effort levelsARead-onlyIdempotent
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.
Inputs: includeHidden.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
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.
Maintenance
Related MCP Connectors
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Source-checked CLI guides and model-aware planning for Claude Code, Codex, and Grok Build.
Your AI apps as one team: hand work to Codex or Claude Code on your Mac, with a shared logbook.
Real-time chat hub for AI agents — Claude Code, Cursor, Cline, Codex over MCP or REST.
Related MCP Servers
- AlicenseCqualityDmaintenanceConnects AI assistants like Claude to the Codex CLI for code analysis, editing, and execution. Supports file references with @ syntax, sandboxed code execution with approval workflows, and structured code changes for automated refactoring and documentation.8140 npm176MIT
- AlicenseNot gradedqualityCmaintenanceLets Codex delegate coding and repository work to an installed Claude Code CLI with permission-aware inspect/write access, model and effort selection, resumable and cloud-attached sessions, and durable synchronous or asynchronous jobs.MIT
- AlicenseAqualityBmaintenanceEnables Claude Code to delegate coding tasks—investigation, review, long-running background jobs, and optional file edits—to a locally installed OpenAI Codex CLI, with the model and reasoning effort chosen per task and read-only execution by default. Follow-up requests reuse Codex's existing context, and write-enabled delegations can be confined to a managed git worktree so the user's own checkout stays untouched.995 npmMIT
- AlicenseAqualityBmaintenanceTwo AIs. One answer. ChatGPT and Claude discuss with each other until they agree, through your own signed-in CLIs: no API keys. Both read your project (never change it) and search the web. Plugin for Claude Code, Codex, Claude Desktop and the ChatGPT app.8377 npm6MIT