# io.github.hampsterx/codex-mcp-bridge (npm · codex-mcp-bridge)

Wraps Codex CLI as MCP tools: codex, review, query, search, structured, ping, listSessions.

- Trust score: 78/100 (medium)
- Change this week: +35
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- npm · `codex-mcp-bridge`: 78/100 (this document), [markdown](https://verifymcp.io/servers/hampsterx-codex-mcp-bridge/codex-mcp-bridge.md), [page](https://verifymcp.io/servers/hampsterx-codex-mcp-bridge/codex-mcp-bridge)

## Channel facts

- Registry: `npm`
- Package: `codex-mcp-bridge`
- Version: `0.9.1`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Supply Chain Security**: 87/100
  - No malware found by supply-chain analysis.
  - Only part of the dependency tree could be resolved (98 of 102), so this covers what we could see, not the whole tree.
  - No install/post-install scripts declared.
  - Only part of the dependency tree could be resolved (98 of 102), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 97/100
  - Source repository is publicly reachable at the declared URL.
  - Cryptographically verified build provenance (signed, bound to hampsterx/codex-mcp-bridge).
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 1 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 65/100
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 1416 tokens (~202/item across 7 items; 7 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 27/100
  - Stability observed for 8 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add hampsterx-codex-mcp-bridge -- npx -y codex-mcp-bridge
```

### Codex

```bash
codex mcp add hampsterx-codex-mcp-bridge -- npx -y codex-mcp-bridge
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "hampsterx-codex-mcp-bridge": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "codex-mcp-bridge"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add hampsterx-codex-mcp-bridge --command npx --arg -y --arg codex-mcp-bridge
```

### Hermes

```yaml
mcp_servers:
  hampsterx-codex-mcp-bridge:
    command: "npx"
    args: ["-y", "codex-mcp-bridge"]
```

### Other

```json
{
  "mcpServers": {
    "hampsterx-codex-mcp-bridge": {
      "command": "npx",
      "args": [
        "-y",
        "codex-mcp-bridge"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-03 (score 78, +1)

No change was recorded against any check on this day. Stability & Change Management went from 23 to 27. That category is still filling its 30-day observation window: 7 days of observed history at the previous scan, 8 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-08-02 (score 77, +72)

- [security improvement] Known CVEs: unverified → partial
- [security improvement] Install scripts: unverified → pass
- [security improvement] Provenance: unverified → pass
- [security improvement] Malware scan: unverified → pass
- [security] The attested source repository moved: hampsterx/codex-mcp-bridge
- [functional improvement] Stability: unverified → 0.23
- [functional improvement] MCP protocol: unverified → pass
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] License: unverified → pass
- [functional improvement] Schema quality: unverified → excellent
- [functional improvement] Tool coverage: unverified → 100
- [functional] Licence: MIT
- [functional] Package version: 0.8.0 → 0.9.1

### 2026-08-01 (score 5, −20)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-31 (score 25, −18)

- [security regression] Malware scan: pass → unverified

### 2026-07-29 (score 43, +18)

- [functional regression] Dependency health: partial → unverified
- [functional improvement] Tool coverage: unverified → 100

### 2026-07-28 (score 25, −18)

- [functional regression] Tool coverage: 100 → unverified
- [functional improvement] Dependency health: unverified → partial
- [functional] First check of Schema quality: unverified

### 2026-07-27 (score 43)

First indexed and scored.

## MCP tools (7)

### `codex` (~492 tokens)

Codex CLI

Execute a prompt via Codex CLI. Codex is an AI coding agent that can generate, analyze, refactor, and explain code with full project context (reads AGENTS.md/CODEX.md automatically).

Capabilities: code generation and refactoring, code analysis and explanation, file reading and modification (when sandbox allows), git operations and terminal commands, multi-turn conversations via sessionId.

When to use a different tool:
\- For analysis of text you already have (plans, docs, opinions), inline it directly in the prompt rather than passing file paths. The files parameter triggers full file I/O and increases timeout pressure.

Tips:
\- Set workingDirectory to the target repo for project-aware responses.
\- Use sandbox "read-only" (default) for analysis, "full-auto" for code changes.
\- Break complex tasks into focused prompts rather than one large request.
\- Resume multi-turn conversations with sessionId (returned in previous response metadata).
\- Include relevant files via the files parameter for targeted context (text and images supported).
\- Set reasoningEffort to control depth: "none" for trivial, "minimal" for lightweight, "low"/"medium" for routine, "high"/"xhigh" for deep analysis.

Input parameters:

- `files` (array): File paths relative to workingDirectory. Supports line ranges: 'path:start-end' (e.g. 'src/lib.rs:900-950'). Text and images supported (images ignore line ranges).
- `maxResponseLength` (integer): Soft limit on response length in words
- `model` (string): Model to use (e.g. o3, gpt-4.1)
- `prompt` (string, required): The prompt to send to Codex
- `reasoningEffort` (string): Reasoning effort level (maps to -c model_reasoning_effort)
- `resetSession` (boolean): Clear this session's conversation history and start fresh (requires sessionId)
- `sandbox` (string): Sandbox level: read-only (default), workspace-write, or full-auto (Codex CLI convenience mode for workspace-write with auto-approve)
- `sessionId` (string): Session ID to resume a previous conversation
- `timeout` (integer): Timeout in milliseconds (default: 60s no files, 180s+30s/file with files, max: 600000)
- `workingDirectory` (string): Working directory for the CLI

### `search` (~179 tokens)

Web Search

Web search via Codex CLI. Searches the web and synthesizes a comprehensive answer with source URLs. Use for current information, documentation lookups, API references, and research questions.

Tips:
\- Ask specific, focused questions for best results.
\- Results include source URLs for verification.
\- Use maxResponseLength to control response verbosity.
\- Default timeout is 2 minutes; increase for complex research queries that may require multiple web fetches.

Input parameters:

- `maxResponseLength` (integer): Soft limit on response length in words
- `model` (string): Model to use (e.g. o3, gpt-4.1)
- `query` (string, required): Search query or question
- `timeout` (integer): Timeout in milliseconds (default: 120000, max: 600000)
- `workingDirectory` (string): Working directory for the CLI

### `query` (~256 tokens)

Quick Query

Lightweight query for analysis or opinions on text you already have. No file reading, no repo exploration, no session state. Pass text in the context parameter. For code execution or file operations, use the codex tool instead.

Use cases: reviewing a plan, critiquing a draft, comparing approaches, answering questions about provided text, generating summaries.

Tips:
\- Pass the text to analyze in the context parameter, not as file paths.
\- Set reasoningEffort to control depth: "none" for trivial, "minimal" for lightweight, "low"/"medium" for routine, "high"/"xhigh" for thorough analysis.
\- Use maxResponseLength to control verbosity.

Input parameters:

- `context` (string): Text to analyze (inline, not file paths)
- `maxResponseLength` (integer): Soft limit on response length in words
- `model` (string): Model to use (e.g. o3, gpt-4.1)
- `prompt` (string, required): The question or instruction
- `reasoningEffort` (string): Reasoning effort level (maps to -c model_reasoning_effort)
- `timeout` (integer): Timeout in milliseconds (default: 60000, max: 600000)

### `review` (~255 tokens)

Native Code Review

Run Codex CLI's native diff-aware review via codex exec review --json. The bridge does not accept or bundle a review prompt; upstream Codex owns the reviewer instructions.

Use for MCP clients that cannot run shell commands but need native Codex review of uncommitted changes, a base branch diff, or a single commit.

Tips:
\- Set workingDirectory to the target git repository.
\- Choose mode "uncommitted", "base", or "commit".
\- Use the codex tool with sandbox "read-only" for free-form review prompts.

Input parameters:

- `base` (string): Base branch or ref. Required when mode is "base".
- `commit` (string): Commit SHA or ref. Required when mode is "commit".
- `mode` (string, required): Diff selector: uncommitted changes, changes against a base branch, or one commit
- `model` (string): Model to use (e.g. o3, gpt-4.1)
- `timeout` (integer): Timeout in milliseconds (default: 180000, max: 600000)
- `title` (string): Optional commit title to display in the review summary
- `workingDirectory` (string, required): Target git repository directory for native review

### `structured` (~160 tokens)

Structured Output

Generate a JSON response conforming to a provided JSON Schema. Use for data extraction, classification, or any task needing machine-parseable output.

Input parameters:

- `files` (array): File paths to include as context (text only, no images). Supports line ranges: 'path:start-end' (e.g. 'src/lib.rs:900-950').
- `model` (string): Model to use (e.g. o3, gpt-4.1)
- `prompt` (string, required): What to generate or extract
- `schema` (string, required): JSON Schema the response must conform to (as a JSON string)
- `timeout` (integer): Timeout in milliseconds (default: 60000)
- `workingDirectory` (string): Working directory for file paths

### `listSessions` (~50 tokens)

List Sessions

List active Codex conversation sessions. Returns session metadata for orchestration (no prompts or responses, just IDs and timing). Use to check available sessions before resuming with the codex tool's sessionId parameter.

### `ping` (~24 tokens)

Health Check

Health check: verifies Codex CLI is installed and authenticated, reports versions and capabilities.

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/hampsterx-codex-mcp-bridge/codex-mcp-bridge#diagnostics

## Score history

- 2026-08-03: 78
- 2026-08-02: 77
- 2026-08-01: 5
- 2026-07-31: 25
- 2026-07-29: 43
- 2026-07-28: 25
- 2026-07-27: 43

## Links

- npm package: https://www.npmjs.com/package/codex-mcp-bridge
- Socket report: https://socket.dev/npm/package/codex-mcp-bridge
- Repository: https://github.com/hampsterx/codex-mcp-bridge
- Changelog RSS feed: https://verifymcp.io/servers/hampsterx-codex-mcp-bridge/codex-mcp-bridge/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/hampsterx-codex-mcp-bridge/codex-mcp-bridge/changelog.json
- HTML version of this page: https://verifymcp.io/servers/hampsterx-codex-mcp-bridge/codex-mcp-bridge