# Codex Subagent (npm · codex-subagent-mcp)

Delegate coding tasks to the OpenAI Codex CLI, installed separately, with explicit model and effort.

- Trust score: 89/100 (high trust)
- Change this week: +3
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-10-23

## Components

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

## Channel facts

- Registry: `npm`
- Package: `codex-subagent-mcp`
- Version: `0.6.0`
- 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-10-23.

- **Supply Chain Security**: 98/100
  - No malware found by supply-chain analysis.
  - No known CVEs affecting this package version or its production dependencies.
  - No install/post-install scripts declared.
  - 30 of 92 dependencies flagged as unhealthy.
- **Provenance & Transparency**: 100/100
  - Source repository is publicly reachable at the declared URL.
  - Cryptographically verified build provenance (signed, bound to parisbs/codex-subagent-mcp).
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 2 days ago).
  - Publishes a security disclosure policy (SECURITY.md).
- **Schema Quality & AI Usability**: 64/100
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 1948 tokens (~216/item across 9 items; 9 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 77/100
  - Stability observed for 23 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 99/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 98% of tool parameters carry a description.
- **Tool Safety**: 88/100
  - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.
  - 1 of 2 tool(s) whose name or description implies an irreversible operation declare an MCP destructiveHint annotation; "codex_follow_up" implies "send" and declares no destructiveHint at all, which the MCP spec reads as destructive by default.
  - An AI judge read all 10 captured unit(s) of tool text and found none that tries to manipulate the model reading it.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### How do I install the Codex Subagent MCP server?

Codex Subagent runs locally as an npm package, launched with npx -y codex-subagent-mcp. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.

### Claude

```bash
claude mcp add parisbs-codex-subagent-mcp -- npx -y codex-subagent-mcp
```

### Cursor

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

### VS Code

```json
{
  "servers": {
    "parisbs-codex-subagent-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "codex-subagent-mcp"
      ]
    }
  }
}
```

### Codex

```bash
codex mcp add parisbs-codex-subagent-mcp -- npx -y codex-subagent-mcp
```

### opencode

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

### OpenClaw

```bash
openclaw mcp add parisbs-codex-subagent-mcp --command npx --arg -y --arg codex-subagent-mcp
```

### Hermes

```yaml
mcp_servers:
  parisbs-codex-subagent-mcp:
    command: "npx"
    args: ["-y", "codex-subagent-mcp"]
```

### Netclaw

```json
{
  "McpServers": {
    "parisbs-codex-subagent-mcp": {
      "Transport": "stdio",
      "Command": "npx",
      "Arguments": [
        "-y",
        "codex-subagent-mcp"
      ]
    }
  }
}
```

### Vellum

```bash
assistant mcp add parisbs-codex-subagent-mcp -t stdio -c npx -a -y codex-subagent-mcp
```

### Other

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

## 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-10-23 (score 89, +1)

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

### 2026-10-22 (score 88, +15)

- [security improvement] Malware scan: unverified → pass

### 2026-10-21 (score 73, −15)

- [security regression] Malware scan: pass → unverified
- [functional regression] Schema quality: 194 → 216
- [functional] Package version: 0.5.0 → 0.6.0

### 2026-10-19 (score 88, +1)

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

### 2026-10-17 (score 87, +1)

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

### 2026-10-14 (score 86, +1)

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

### 2026-10-12 (score 85, +1)

- [functional improvement] Security disclosure: unverified → pass

### 2026-10-11 (score 84, +2)

- [functional regression] Security disclosure: pass → unverified

## MCP tools (9)

### `codex_doctor` (~184 tokens)

Check the Codex CLI installation

Check whether the local Codex CLI is installed, recent enough, signed in and able to load its configuration, and report the exact steps to fix it if not. Run this when any other tool reports the CLI is unavailable, or before relying on delegation for the first time. It only inspects the installation; it never installs or repairs anything. Opt in with extended for a slow, networked config.load report from codex doctor --json.

Input parameters:

- `extended` (boolean): Run the slow, networked Codex doctor report in addition to the cheap diagnosis.
- `refresh` (boolean): Re-probe the CLI instead of reusing the cached diagnosis.
- `working_dir` (string): Absolute directory to run the check in. Codex loads the configuration of the directory it runs in, so pass the one a delegation would use. Defaults to this server's own.

### `list_codex_models` (~126 tokens)

List Codex models

List the Codex models available on this machine, with the reasoning-effort levels each one supports. Read from the installed Codex CLI, with a warned static fallback if its catalog cannot be read. Call this before codex_delegate when choosing a model explicitly.

Input parameters:

- `refresh` (boolean): Bypass the cache and re-read the catalog from the CLI.
- `working_dir` (string): Absolute directory to read the catalog in. A project you have trusted in Codex can set its own catalog, so pass the directory a delegation would use. Defaults to this server's own.

### `codex_recommend` (~114 tokens)

Recommend a Codex model and effort

Given a task description, recommend which Codex model and reasoning effort to delegate it with. Runs no model call; applies a documented matrix reconciled against the installed catalog.

Input parameters:

- `priority` (string): Bias the reasoning effort: quality raises it, latency and cost lower it. Default balanced.
- `task_description` (string, required): What the delegated task involves, in one or two sentences.
- `working_dir` (string): Absolute directory whose Codex configuration and model catalog should be used. Defaults to this server's own.

### `codex_delegate` (~797 tokens)

Delegate a task to Codex

Delegate a task to the local Codex CLI (OpenAI's coding agent), choosing model and reasoning effort. Use it when the user asks for Codex, or when handing work off clearly serves their request: a second opinion from a different model family, or an investigation that would otherwise flood this conversation. When the user has not named a model, call codex_recommend first and present its suggested model and effort to the user in the same message in which you say you are going to delegate, then pass both explicitly here. That recommendation is advice for an already-authorised delegation, not a replacement for the user's own preference. Everything passed in prompt, context and target_files is sent to OpenAI, and every run spends the user's own Codex usage, so do not delegate what you can answer directly, and tell the user when you delegate. Codex runs read-only unless a different default sandbox is configured. Set sandbox to workspace-write to let it edit files, if this server's sandbox ceiling allows it: a correctly configured server states the ceiling in its instructions, and a call above it is refused. Codex cannot see this conversation, so pass everything it needs in prompt, context, and target_files.

Input parameters:

- `acceptance_criteria` (array): Concrete conditions that must hold for the task to be considered done.
- `add_dirs` (array): Additional absolute directories that should be writable alongside working_dir.
- `auto_approve` (boolean): Adds --approve-for-me so Codex auto-approves its own commands. Only applies when sandbox is workspace-write.
- `context` (string): Background Codex needs: prior findings, constraints, relevant excerpts.
- `label` (string): Your own short name for this kind of task, stored verbatim in the local usage log and never sent to Codex: 1 to 64 characters, no control or bidirectional-control characters. A follow-up without one…
- `mode` (string): blocking (default) waits and streams progress; background returns a job_id immediately.
- `model` (string): Catalog slug from list_codex_models. If omitted, the configured default is used; with no default configured the call is refused and the recommended model is returned.
- `output_schema` (object): A JSON Schema object for this turn's final message, which then comes back as JSON in a delimited block. OpenAI's structured outputs apply: every object needs "additionalProperties": false and every p…
- `prompt` (string, required): The task for Codex. Be specific and self-contained: Codex cannot see this conversation.
- `reasoning_effort` (string): Reasoning depth, independent of model choice. Uses the configured default or the model's default when omitted. Clamped to supported levels within the configured ceiling; refused if none qualify.
- `sandbox` (string): Sandbox policy. Uses the configured default when omitted; without one, Codex runs read-only.
- `skip_git_repo_check` (boolean): Allow running outside a git repository.
- `system_instructions` (string): Persona or extra rules inherited from the orchestrator, layered on the built-in quality contract.
- `target_files` (array): Paths Codex should focus on, relative to working_dir.
- `timeout_seconds` (integer): Wall-clock budget. Defaults to 1800s.
- `use_worktree` (boolean): Run in a managed git worktree. Writes outside it remain subject to the sandbox policy and add_dirs.
- `web_search` (boolean): Enable Codex's API-backed live web-search tool for this run. In a read-only sandbox, shell commands have no network access, so this is the route to current external information. When omitted, Codex's…
- `working_dir` (string): Absolute path Codex uses as its working root.

### `codex_follow_up` (~371 tokens)

Continue a Codex session

Send a follow-up message to a previous delegation using its thread_id. Codex retains the earlier context, so only the new instruction needs to be sent. Like a delegation, it is sent to OpenAI and spends the user's Codex usage.

Input parameters:

- `auto_approve` (boolean): Not supported on follow-ups: true is refused and nothing runs.
- `label` (string): Your own short name for this kind of task, stored verbatim in the local usage log and never sent to Codex: 1 to 64 characters, no control or bidirectional-control characters. A follow-up without one…
- `model` (string): Override the model for this turn. Defaults to the thread's last model from memory or, on a registry miss, Codex's session file; if neither has it, the configured default, else the call is refused.
- `output_schema` (object): A JSON Schema object for this turn's final message, which then comes back as JSON in a delimited block. OpenAI's structured outputs apply: every object needs "additionalProperties": false and every p…
- `prompt` (string, required): The follow-up instruction.
- `reasoning_effort` (string): Override the reasoning effort for this turn. Defaults to the thread's last effort when the model is unchanged, otherwise to the configured or model default.
- `sandbox` (string): Sandbox policy for this turn. Uses the configured default when omitted; read-only when unset.
- `thread_id` (string, required): The thread_id reported by a previous codex_delegate call.
- `timeout_seconds` (integer)
- `working_dir` (string): Absolute directory to resume in. Defaults to the directory the thread last ran in.

### `codex_job_status` (~68 tokens)

Check a background delegation

Report the state and recent activity of a background delegation started with mode=background. Call it with no job_id to list every known job.

Input parameters:

- `include_activity` (boolean): Include the recent progress log for the job.
- `job_id` (string): Omit to list all jobs.

### `codex_usage` (~141 tokens)

Summarise the local usage log

Summarise this server's local usage log (CODEX_SUBAGENT_USAGE_LOG) over a window: per group, the number of delegation processes, their outcomes, commands, durations and the tokens the Codex CLI reported. Reads local files only and runs no Codex process. It never reports quota, credits or remaining allowance.

Input parameters:

- `group_by` (string): Group by the applied model and effort (default), the caller's label, the outcome, or the kind.
- `since_hours` (number): How far back to look, in hours: greater than 0 and at most 8,760. Defaults to 168 (one week).

### `codex_job_result` (~44 tokens)

Read a background delegation's result

Return the full output of a finished background delegation. Errors if the job is still running.

Input parameters:

- `job_id` (string, required): The job_id returned by codex_delegate.

### `codex_job_cancel` (~33 tokens)

Cancel a background delegation

Terminate a running background delegation.

Input parameters:

- `job_id` (string, required): The job_id returned by codex_delegate.

## Diagnostics

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

## Score history

- 2026-10-23: 89
- 2026-10-22: 88
- 2026-10-21: 73
- 2026-10-20: 88
- 2026-10-19: 88
- 2026-10-18: 87
- 2026-10-17: 87
- 2026-10-16: 86
- 2026-10-15: 86
- 2026-10-14: 86
- 2026-10-13: 85
- 2026-10-12: 85
- 2026-10-11: 84
- 2026-10-06: 82
- 2026-10-05: 81
- 2026-10-04: 81
- 2026-10-03: 80
- 2026-10-02: 65
- 2026-10-01: 79
- 2026-09-30: 64

## Common questions

### What is the Codex Subagent MCP server?

Codex Subagent is an MCP server listed in the public MCP registry as io.github.parisbs/codex-subagent-mcp. Delegate coding tasks to the OpenAI Codex CLI, installed separately, with explicit model and effort. This page covers its npm package (codex-subagent-mcp).

### Is the Codex Subagent MCP server safe to use?

Codex Subagent scores 89 out of 100 on VerifyMCP. We found no known CVEs affecting it as of 23 October 2026. It declares no install or post-install scripts. Its build provenance is signed and verified. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.

### What tools does the Codex Subagent MCP server expose?

Codex Subagent exposes 9 tools: codex_doctor, list_codex_models, codex_recommend, codex_delegate, codex_follow_up, and 4 more. Their descriptions and schemas cost roughly 1,878 tokens of context every time the server is loaded.

### Is the Codex Subagent MCP server still maintained?

Codex Subagent is still listed as active in the MCP registry. We last reached this channel on 23 October 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.

### What licence is the Codex Subagent MCP server under?

Codex Subagent declares the MIT licence, which is OSI-approved. That covers the source only, and says nothing about the cost of any service it calls.

## Links

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