Skip to main content
Glama

codex-consultant

CI License: MIT Node.js 22+

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.

Related MCP server: Lumen Bridge

Features

  • codex_consult for a fresh read-only Codex thread;

  • codex_continue using thread/resume;

  • codex_review for 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:

  1. initialize;

  2. initialized;

  3. thread/start;

  4. turn/start;

  5. matching item/agentMessage/delta, item/completed, and turn/completed notifications.

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.

Available Tools

3 tools
codex_consultConsult CodexB
Read-only

Ask Codex for a focused, read-only second opinion in a fresh thread.

Inputs: prompt (required), cwd, model.

codex_continueContinue Codex ThreadA
Read-only

Continue an existing Codex thread in the same read-only consultant mode.

Inputs: prompt (required), threadId (required).

codex_reviewReview Project with CodexA
Read-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

    A3.8/5.0

    Scored across 3 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    All tools follow the consistent codex_<verb> pattern with clear, simple verbs (consult, continue, review). No mixed conventions or vague names.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      Bridges MCP clients with local Codex CLI to execute autonomous coding tasks, manage threads, and inspect history via SQLite state.
      13
      4
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      A 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
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      2
      MIT