codex-consultant
Provides tools to interact with Codex, OpenAI's coding agent, enabling fresh read-only consultations, continuation of existing threads, and focused project reviews with optional working directory and model overrides.
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-consultant Review my project for potential issues and suggest fixes"
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-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 --stdioThe 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.
Related MCP server: Lumen Bridge
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 |
|
| Fresh read-only consultation |
|
| Continue an existing thread |
|
| 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 checknpm 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 pathMCP 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 devSee CONTRIBUTING.md, SECURITY.md, and
CHANGELOG.md before opening a pull request.
License
MIT. See LICENSE.
Available Tools
3 toolscodex_consultConsult CodexBRead-only
Ask Codex for a focused, read-only second opinion in a fresh thread.
Inputs: prompt (required), cwd, model.
codex_continueContinue Codex ThreadARead-only
Continue an existing Codex thread in the same read-only consultant mode.
Inputs: prompt (required), threadId (required).
codex_reviewReview Project with CodexARead-only
Ask Codex for a focused, read-only code or project review rooted at the supplied cwd.
Inputs: cwd (required), prompt (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
codex_consult and codex_review both offer read-only Codex input, but review is explicitly scoped to code/project review at a cwd while consult is a general second opinion. codex_continue is clearly distinct. The overlap is minor and descriptions help.
All tools follow the consistent codex_<verb> pattern with clear, simple verbs (consult, continue, review). No mixed conventions or vague names.
Three tools is exactly right for a focused consultant server: ask for a consult, continue it, and request a review. Nothing feels missing or excessive.
The server's purpose is read-only Codex consultation and review. The tools cover starting a consultation, continuing a thread, and performing a project review—no obvious dead ends or missing operations for this narrow domain.
Maintenance
Related MCP Connectors
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
Read project context and manage tasks in MCPBinder, with access you control.
A paid remote MCP for OpenAI Codex agent coordination MCP, built to return verdicts, receipts, usage
Related MCP Servers
- AlicenseCqualityDmaintenanceBridges MCP clients with local Codex CLI to execute autonomous coding tasks, manage threads, and inspect history via SQLite state.134Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients and external AI supervisors to oversee and steer native Codex sessions through a thin local stdio bridge. It exposes eleven codex_* supervisory tools for tasks such as listing threads, starting turns, observing progress, steering, responding to approvals, interrupting, checkpointing, and rolling over work.MIT
- AlicenseNot gradedqualityBmaintenanceA local stdio MCP server that lets any MCP client start a Codex thread and continue it by opaque thread ID through the codex and codex-reply tools, with fail-closed sandboxing and approval policies. It restores the removed Codex CLI MCP integration by bridging clients like OpenCode to the official Codex SDK.MIT
- AlicenseAqualityBmaintenanceEnables MCP clients to start new Codex conversations and continue existing threads, exposing codex and codex-reply tools over stdio via the Codex app-server protocol.2MIT