codex-consultant MCP server
Commit Oct 20, 2026Provides a read-only bridge to the Codex app-server, allowing AI clients to consult, continue threads, or review projects via MCP tools.
Also known as amu3dev/codex-consultant
- Stars
- 0
- Tools
- 3
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 20, 2026
- License
- MIT
What is codex-consultant MCP?
codex-consultant provides a read-only bridge to the Codex app-server, allowing AI clients to consult, continue threads, or review projects via MCP tools. It exposes 3 tools, such as codex_consult, codex_continue, codex_review.
Summary generated from the project's README
About codex-consultant MCP server
Consulting a Codex model for a second opinion or project review from within an AI client is what this bridge enables. It acts as a local adapter that connects MCP hosts to the Codex app-server using stdio. Developers running macOS with the Codex CLI installed can use this to interact with their existing authenticated Codex sessions without needing to manage separate API keys in their MCP configuration.
The server provides three specific tools: codex_consult for starting fresh read-only threads, codex_continue for resuming existing conversations via thread IDs, and codex_review for analyzing specific projects or directories. It manages the entire lifecycle of the app-server process, including request correlation and cleanup, while maintaining a read-only sandbox by default. This setup ensures that the AI client receives structured metadata like thread IDs and model details alongside the primary assistant response.
What you can do with it
- 1Get a second opinionAsk the Codex model for a fresh, read-only consultation on a specific coding problem.
- 2Resume existing conversationsContinue a previous discussion by providing a specific thread ID to the client.
- 3Perform project reviewsRequest a focused review of a codebase by specifying a working directory.
Written from the project's README. Every use case is checked against a quote from it.
codex-consultant MCP tools 3
Detected from the READMEcodex_consultcodex_continuecodex_review
Configuration
NODE_ENV
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableamu3dev/codex-consultant is public and reachablegithub.com/amu3dev/codex-consultant ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-20github.com/amu3dev/codex-consultant ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model3 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubcodex-consultant
Thin local MCP bridge for Codex app-server. Ask Codex for a focused second opinion, continue a thread, or review a project through standard MCP tools—while keeping the consultation read-only by default.
This is an independent community project. It is not affiliated with or endorsed by OpenAI.
Why this exists
Recent Codex CLI versions removed the deprecated codex mcp-server entry point.
This adapter uses the supported app-server interface instead:
codex app-server --stdio
The adapter owns the protocol lifecycle, request correlation, event collection, timeouts, diagnostics, and child-process cleanup so an MCP host only sees the consultant tools and the final answer.
Features
codex_consultfor a fresh read-only Codex thread;codex_continueusingthread/resume;codex_reviewfor a focused project review;- optional working-directory and model overrides;
approvalPolicy: "never"and read-only sandbox defaults;- assistant streaming and terminal-turn tracking;
- JSON-RPC request correlation and newline-delimited framing;
- stderr-only diagnostics and protocol-only MCP stdout;
- bounded timeouts, malformed-frame handling, and graceful cleanup;
- deterministic offline checks plus live protocol and end-to-end smoke tests.
Architecture
flowchart LR
Host[MCP host] <-->|MCP JSON-RPC over stdio| Adapter[codex-consultant]
Adapter <-->|app-server JSON lines| App[Codex app-server]
App -->|thread and turn events| Adapter
App --> Model[Codex model]
The app-server process starts lazily on the first Codex tool call and remains
alive for the MCP server lifetime. Each codex_consult call creates a fresh
thread. The adapter exposes no arbitrary shell-execution tool.
Tools
| Tool | Input | Purpose |
|---|---|---|
codex_consult |
{ prompt, cwd?, model? } |
Fresh read-only consultation |
codex_continue |
{ threadId, prompt } |
Continue an existing thread |
codex_review |
{ prompt, cwd } |
Read-only code or project review |
The final assistant answer is returned as the primary MCP text content. Minimal metadata—thread ID, turn ID, model, status, duration, and assistant message ID— is returned as structured content.
Requirements
- macOS with the Codex CLI installed;
- Codex CLI 0.154.0 or a compatible app-server protocol;
- Node.js 22 or newer;
- an authenticated Codex session for live calls;
- an MCP host that supports local stdio servers.
The default binary path is /opt/homebrew/bin/codex. Change the source constant
if your installation uses another path.
Install and verify
git clone https://github.com/amu3dev/codex-consultant.git
cd codex-consultant
npm ci
npm run check
npm run check runs typechecking, deterministic tests, the TypeScript build, and
an MCP initialize/tools-list smoke check. It does not require a live model call.
For a locally authenticated Codex installation, run the layered live checks:
npm run smoke:app-server # raw app-server lifecycle
npm run smoke:wrapper # TypeScript wrapper
npm run smoke:continue # thread/resume lifecycle
npm run smoke:mcp # complete MCP -> app-server -> model path
MCP configuration
Build the server first and find the Node executable with command -v node.
Copy examples/mcp-config.json, replacing its three
/absolute/path/to/... placeholders:
{
"mcpServers": {
"codex": {
"command": "/absolute/path/to/node",
"args": [
"/absolute/path/to/codex-consultant/dist/index.js"
],
"cwd": "/absolute/path/to/codex-consultant",
"env": {
"NODE_ENV": "production"
}
}
}
}
No Codex API key belongs in this configuration. The adapter uses the local Codex authentication and configuration already available to the app-server.
Protocol and safety
The verified lifecycle is:
initialize;initialized;thread/start;turn/start;- matching
item/agentMessage/delta,item/completed, andturn/completednotifications.
Codex 0.154.0 accepts standard JSON-RPC requests with "jsonrpc": "2.0", but
its server-emitted responses and notifications omit that member. The adapter
handles this current wire-format detail while rejecting malformed frames. See
docs/protocol.md for the exact payloads and event contract.
The read-only policy is a least-authority default, not a guarantee that supplied
prompts or repository contents are non-sensitive. Choose cwd carefully and
minimize confidential context before invoking the tools.
Development
Useful commands:
npm run typecheck
npm test
npm run build
npm run verify:mcp
npm run dev
See CONTRIBUTING.md, SECURITY.md, and
CHANGELOG.md before opening a pull request.
License
MIT. See LICENSE.
codex-consultant MCP questions
What tools does codex-consultant MCP provide?
It exposes 3 tools, including codex_consult, codex_continue, codex_review.
Does this server require a Codex API key in the MCP configuration?
No, the adapter uses the local Codex authentication and configuration already available to the app-server.
What are the system requirements for running codex-consultant?
You need macOS with the Codex CLI installed (version 0.154.0 or compatible), Node.js 22 or newer, and an authenticated Codex session.