Codex Discussion MCP
# Codex Discussion MCP
[](https://www.npmjs.com/package/@mirolab/codex-discussion-mcp)
[](https://www.npmjs.com/package/@mirolab/codex-discussion-mcp)
[](https://github.com/smallmiro/codex-discussion-mcp/issues)
[](https://github.com/smallmiro/codex-discussion-mcp#readme)
[](LICENSE)
[](https://github.com/sponsors/smallmiro)
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](https://github.com/smallmiro/codex-discussion-mcp/blob/main/docs/skills.md) · [Agent skill](skills/codex-discussion/SKILL.md)
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](docs/publishing.md)
## Requirements
- Node.js **22.14 or later** and npm
- [Codex CLI](https://developers.openai.com/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.
## Installation
Install the published package globally:
```bash
npm install -g @mirolab/codex-discussion-mcp
codex-discussion-mcp --help
```
You can also run it without a global installation. Register this command in your
MCP configuration:
```bash
npx -y @mirolab/codex-discussion-mcp@0.1.5
```
This 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:
```json
{ "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 `npm install -g @mirolab/codex-discussion-mcp@latest`. |
| Project-local npm installation | In the installation's project, run `npm install @mirolab/codex-discussion-mcp@latest`, preserving your dependency/devDependency convention. |
| Version-pinned `npx` configuration | Change the configured `@mirolab/codex-discussion-mcp@VERSION` argument to the desired newer version. A global install does not change that pin. |
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](docs/skills.md#6-update-or-remove-the-skill);
updating npm does not overwrite the copy or its customizations. See
[changelog](CHANGELOG.md) and
[release notes](https://github.com/smallmiro/codex-discussion-mcp/releases).
## Register with Claude Code
After installing globally, register it for all projects:
```bash
claude mcp add --transport stdio --scope user codex-discussion -- codex-discussion-mcp
claude mcp get codex-discussion
```
Register without a global installation:
```bash
claude mcp add --transport stdio --scope user codex-discussion -- \
npx -y @mirolab/codex-discussion-mcp@0.1.5
```
To 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 | `~/.kiro/settings/mcp.json` | `.kiro/settings/mcp.json` |
| Antigravity CLI | `~/.gemini/config/mcp_config.json` | `.agents/mcp_config.json` |
```json
{
"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:
```json
{ "command": "codex-discussion-mcp", "args": [] }
```
Host configuration formats may vary by installed version. See the official
[Claude Code documentation](https://code.claude.com/docs/en/mcp),
[Kiro documentation](https://kiro.dev/docs/mcp/configuration/), and
[Antigravity documentation](https://www.antigravity.google/docs/mcp).
## 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.
```json
{
"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](docs/remote-app-server.md). The MCP
package's connection currently remains local stdio.
## Ask your agent
For a reusable user guide, install the optional
[Codex Discussion skill](skills/codex-discussion/SKILL.md) using the
[skill user manual](https://github.com/smallmiro/codex-discussion-mcp/blob/main/docs/skills.md).
> 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:
```bash
npx skills add smallmiro/codex-discussion-mcp --skill codex-discussion
```
For a global installation across your local projects, add `-g`:
```bash
npx skills add smallmiro/codex-discussion-mcp --skill codex-discussion -g
```
Installing 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](https://github.com/smallmiro/codex-discussion-mcp/blob/main/docs/skills.md)
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 |
|---|---|---|
| `models_list` | `includeHidden?` | Model and effort catalog, retrieval time, package update status |
| `discussion_start` | `message`, `cwd?`, `model?`, `effort?` | New `discussionId`, `turnId`, selected settings, current status |
| `discussion_reply` | `discussionId`, `message`, `model?`, `effort?` | New turn in the same conversation |
| `discussion_forget` | `discussionId` | Release inactive local output; preserve saved history |
| `discussion_read` | `discussionId`, `turnId?`, `cursor?`, `limit?`, `waitMs?` | Status, public messages, `nextCursor`, errors |
| `discussion_cancel` | `discussionId`, `turnId` | 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:
1. If omitted on the first question, use the catalog's default model and that model's default effort.
2. 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.
3. If the model changes and effort is omitted, use the new model's default effort.
4. 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:
```text
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](AGENTS.md) for the repository map, behavioral contracts, validation
commands, and release guidance for coding agents.
```bash
npm ci
npm run check
npm run verify:package
npm run smoke -- --models-only
```
`verify: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:
```bash
npm run smoke -- --inference
```
This 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](docs/publishing.md) ·
[Design](docs/superpowers/specs/2026-10-25-codex-discussion-mcp-design.md) ·
[Development plan](docs/superpowers/plans/2026-10-25-codex-discussion-mcp.md)
## License
[MIT](LICENSE)
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.