Codex Subagent
NPM · CODEX-SUBAGENT-MCP
Delegate coding tasks to the OpenAI Codex CLI, installed separately, with explicit model and effort.
Available components
Last scanned (9 hours ago)
Scores higher than 90% of npm servers
Category Developer Tools
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. How we score → Why this is hard to score →
Supply Chain Security98
- No malware found by supply-chain analysis.Pass
- No known CVEs affecting this package version or its production dependencies.Pass
- No install/post-install scripts declared.Pass
- 30 of 92 dependencies flagged as unhealthy. View diagnostics → Partial
Provenance & Transparency100
- Source repository is publicly reachable at the declared URL. View diagnostics → Pass
- Cryptographically verified build provenance (signed, bound to parisbs/codex-subagent-mcp). View diagnostics → Pass
- Clear OSI-approved license (MIT).Pass
- Actively maintained (last published 2 days ago).Pass
- Publishes a security disclosure policy (SECURITY.md).Pass
Schema Quality & AI Usability64
- AI-judged instruction clarity (excellent).Pass
- 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. See how to fix → Fail
- Usage-examples check failed: none of the tools include examples. See how to fix → Fail
Stability & Change Management77
- Stability observed for 23 of 30 days with no destabilising changes; credit accrues until the full window elapses.Partial
Tool Coverage99
- 100% of tools have a non-trivial description (not blank, and not just the tool's name).Pass
- 98% of tool parameters carry a description.Partial
Tool Safety88
- No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.Pass
- 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. See how to fix → Partial
- An AI judge read all 10 captured unit(s) of tool text and found none that tries to manipulate the model reading it.Pass
Capabilities100
- Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.Pass
Every change we have recorded for this component, newest first. Security-relevant changes are always shown. ▲ marks a change for the better, ▼ a change for the worse; unmarked changes are neutral.
- 23 Oct 26 +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.
- 22 Oct 26 +15
- Malware scan: unverified → pass ▲ security
- 21 Oct 26 −15
- Malware scan: pass → unverified ▼ security
- Schema quality: 194 → 216 ▼ functional
- Package version: 0.5.0 → 0.6.0 functional
- 19 Oct 26 +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.
- 17 Oct 26 +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.
- 14 Oct 26 +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.
- 12 Oct 26 +1
- Security disclosure: unverified → pass ▲ functional
- 11 Oct 26 +2
- Security disclosure: pass → unverified ▼ functional
Diagnostic detail from the automated scan of this channel: what the scanner observed at each step, so you can see exactly where a check passed or failed. It is informational only and never changes the trust score.
Captured 23 Oct 2026 · Analysed npm/codex-subagent-mcp@0.6.0
Provenance Verified
A signed build attestation was found and verified, binding this exact artifact to the source repository it claims to come from.
| Result | Verified |
|---|---|
| Ecosystem | npm |
| Reason | Verified |
| Discovered via | Registry attestation endpoint |
| Source repo | parisbs/codex-subagent-mcp |
| Certificate issuer | https://token.actions.githubusercontent.com |
| Certificate SAN | https://github.com/parisbs/codex-subagent-mcp/.github/workflows/publish.yml@refs/tags/v0.6.0 |
| Rekor log index | 3346484254 |
| Predicate type | SLSA build provenance https://slsa.dev/provenance/v1 |
| Subject digest | sha512:5b52caf49ff59739e0bcaf354372659e8f4ee570ad50741607f2663e5e9b33cf3c115656b48ed06230730277da026f467a17e3ce9c3fa38e8196dc91c |
Background: How many MCP packages publish verified provenance →
Dependencies 92 packages
| Packages resolved | 92 |
|---|---|
| Stale | 30 |
| Tree resolution | Complete |
Background: SBOMs and build attestations, explained →
The tools this component advertises to a client, with an estimated token cost for each. Expand a tool to see its parameters and schema. The per-tool counts are indicative and are not scored directly; the schema's total context footprint is one signal in Schema Quality & AI Usability. A tool's description is untrusted text the model reads on every call, which is what makes this list a security surface and not just an inventory: how tool poisoning works →
codex_delegate Delegate a task to Codex ~797
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.
| Name | Type | Req | Description |
|---|---|---|---|
| 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 | yes | 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. |
No output schema declared.
No examples provided.
codex_doctor Check the Codex CLI installation ~184
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.
| Name | Type | Req | Description |
|---|---|---|---|
| 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. |
No output schema declared.
No examples provided.
codex_follow_up Continue a Codex session ~371
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.
| Name | Type | Req | Description |
|---|---|---|---|
| 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 | yes | 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 | yes | 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. |
No output schema declared.
No examples provided.
codex_job_cancel Cancel a background delegation ~33
Terminate a running background delegation.
| Name | Type | Req | Description |
|---|---|---|---|
| job_id | string | yes | The job_id returned by codex_delegate. |
No output schema declared.
No examples provided.
codex_job_result Read a background delegation's result ~44
Return the full output of a finished background delegation. Errors if the job is still running.
| Name | Type | Req | Description |
|---|---|---|---|
| job_id | string | yes | The job_id returned by codex_delegate. |
No output schema declared.
No examples provided.
codex_job_status Check a background delegation ~68
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.
| Name | Type | Req | Description |
|---|---|---|---|
| include_activity | boolean | – | Include the recent progress log for the job. |
| job_id | string | – | Omit to list all jobs. |
No output schema declared.
No examples provided.
codex_recommend Recommend a Codex model and effort ~114
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.
| Name | Type | Req | Description |
|---|---|---|---|
| priority | string | – | Bias the reasoning effort: quality raises it, latency and cost lower it. Default balanced. |
| task_description | string | yes | 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. |
No output schema declared.
No examples provided.
codex_usage Summarise the local usage log ~141
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.
| Name | Type | Req | Description |
|---|---|---|---|
| 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). |
No output schema declared.
No examples provided.
list_codex_models List Codex models ~126
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.
| Name | Type | Req | Description |
|---|---|---|---|
| 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. |
No output schema declared.
No examples provided.
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.
npm · codex-subagent-mcp
claude mcp add parisbs-codex-subagent-mcp -- npx -y codex-subagent-mcp
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.