Skip to main content
Glama
amu3dev

codex-consultant

by amu3dev
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

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: Engineering Knowledge Graph MCP Server

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
cwdNo
modelNo
promptYes

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context: 'fresh thread' and 'focused' indicate isolation and scope. However, it does not disclose details like whether the fresh thread has access to the current conversation context, or what happens to the thread after the consultation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, well-structured sentence that front-loads the core action and scope. Every word earns its place, and the key qualifiers ('focused', 'read-only', 'fresh thread') are packed efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no output schema and 0% schema description coverage, so the description carries the full burden. It explains the purpose but omits parameter semantics (cwd, model), return behavior, and any caveats about the fresh thread's context. For a tool with three parameters and no structured schema help, this is incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for the three parameters (cwd, model, prompt). The description only mentions 'Ask Codex' and 'fresh thread', which implies the prompt parameter but does not explain cwd or model. This is a significant gap for a tool with undocumented parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Ask'), a resource ('Codex'), and a clear scope ('focused, read-only second opinion in a fresh thread'). It distinguishes the tool from siblings by emphasizing 'second opinion' and 'fresh thread', though it does not explicitly name the sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use this tool: when a focused, read-only second opinion is needed. It does not explicitly state when not to use it or name alternatives like codex_continue or codex_review, leaving some routing to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

codex_continueContinue Codex ThreadA
Read-only

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

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYes
threadIdYes

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=false, covering the safety profile. The description adds the 'read-only consultant mode' context but does not disclose additional behavioral traits such as behavior when the thread ID is invalid or what happens after sending the prompt. This is acceptable for a non-destructive continuation tool, but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence with no filler: the verb, resource, and mode are front-loaded, and every word earns its place. It is appropriately sized for a simple continuation tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter tool with annotations covering safety and no output schema, the description is largely sufficient: an agent can infer threadId and prompt from the schema and the continuation intent. It falls short of full completeness by not stating what response or result to expect, but the operation is simple enough that this is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for the undocumented threadId and prompt parameters. It only implies threadId through 'existing thread' and prompt through 'continue,' but it does not explain where threadId comes from, what prompt should contain, or any format constraints beyond minLength.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Continue'), a specific resource ('an existing Codex thread'), and the mode ('read-only consultant mode'). This clearly differentiates it from the sibling tools codex_consult and codex_review, which imply starting or reviewing rather than continuing an existing thread.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The word 'existing' implies this tool is for continuing a prior thread rather than starting a new consultation, but it never explicitly states when to use this versus codex_consult or codex_review. No alternatives or exclusions are named, so the usage guidance is only implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

codex_reviewReview Project with CodexA
Read-only

Ask Codex for a focused, read-only code or project review rooted at the supplied cwd.

ParametersJSON Schema
NameRequiredDescriptionDefault
cwdYes
promptYes

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the 'focused, read-only' framing and the cwd-rooting behavior, which is useful context. It does not disclose details like whether the review is synchronous, how long it may take, or what the output format is, but the annotations carry the main safety burden.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no wasted words. It conveys the action, the resource, the mode (read-only), and the scoping constraint efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter tool with read-only annotations, the description is mostly complete. However, with no output schema and no guidance on what a review result looks like or how the prompt should be structured, an agent may still be uncertain about invocation details. The sibling tools are not differentiated, which is a minor completeness gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for parameter meaning. It mentions 'cwd' as the root location and 'prompt' implicitly as the review request, but it does not explain the expected format, length, or content of the prompt, nor the role of cwd beyond 'rooted at'. This is adequate but minimal.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Ask Codex for'), a resource ('code or project review'), and a key scoping constraint ('rooted at the supplied cwd'). It clearly distinguishes the tool as a review-focused operation, though it does not explicitly name or differentiate from its siblings codex_consult and codex_continue.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for review tasks and emphasizes 'focused, read-only', which suggests when it is appropriate. However, it does not explicitly state when to prefer this tool over codex_consult or codex_continue, nor does it provide exclusions or alternative conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedcodex_consult
    • First observedcodex_continue
    • First observedcodex_review
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

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

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • codex-mcp-server

    4dhxm
    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
    577 npm
    4
    Apache 2.0

  • Lumen Bridge

    diabetic0
    A
    license
    Not graded
    quality
    B
    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

  • WebGPT Codex Bridge

    hsdc1258
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables continuing a local coding task from your own web ChatGPT account by exposing project-scoped read and apply tools over MCP, with no inference API dependency.
    MIT