# Codex Subagent [Health: Active]

**Category:** 🤖 Coding Agents  
**Repository:** https://github.com/parisbs/codex-subagent-mcp  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/codex-subagent

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

## Tools
Capabilities this server exposes over MCP:

- **codex_doctor** — Check the Codex CLI installation and report how to fix it; opt in with `extended: true` for a slow, networked `config.load` report.
- **list_codex_models** — List available models and their reasoning-effort levels.
- **codex_recommend** — Suggest a model and effort for a described task.
- **codex_delegate** — Run a task, blocking or in the background, optionally returning JSON that matches a schema.
- **codex_follow_up** — Continue a previous delegation using its `thread_id`, with or without a schema.
- **codex_job_status** — Check a background delegation.
- **codex_job_result** — Read a finished background delegation's output.
- **codex_job_cancel** — Stop a running background delegation.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

## Documentation

## What Codex Subagent does

Codex Subagent MCP server exposes OpenAI Codex CLI operations as MCP tools for an agent such as Claude Code. The calling agent remains responsible for orchestration while Codex handles a delegated coding task on the local machine. Prompts are sent through the installed CLI, so the server does not store or provide separate OpenAI credentials.

A delegation can request a specific model and reasoning-effort level from the models reported by the local Codex installation. Results identify the applied model, effort, sandbox, working directory, duration, token usage, and thread ID. An optional output schema can make the response JSON suitable for further automated handling.

## How it works

The Codex Subagent MCP server starts the Codex CLI as a local process and passes the task through its standard invocation path. Delegations may block until completion or return a job ID for background execution. Background jobs can be inspected, read after completion, or cancelled. Up to eight background jobs may run concurrently by default, with an environment variable available to lower that limit.

Follow-up requests use a prior thread ID so Codex can continue with its existing context. The server repeats the model, effort, and directory settings on follow-ups. Cancellation, timeout, or shutdown stops Codex and commands started by that run.

## Setup and configuration

Install Node.js 22 or later, install the Codex CLI separately, place it on PATH, and sign in to Codex. A Claude Code installation can register the server with:

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

The repository also documents platform setup and Claude Desktop installation. Run `codex_doctor` to check whether the CLI is available and learn how to correct installation problems. Its extended mode performs a slower, networked configuration report.

## Tools and capabilities

The available MCP tools cover the full delegation lifecycle:

- `codex_doctor` checks the local CLI installation.
- `list_codex_models` reports available models and reasoning levels.
- `codex_recommend` suggests model and effort settings for a described task.
- `codex_delegate` runs a foreground or background task and can enforce an output schema.
- `codex_follow_up` continues a delegation by thread ID.
- `codex_job_status`, `codex_job_result`, and `codex_job_cancel` manage background work.

## Limitations and notes

Read-only execution is the default. Writing requires an explicit workspace-write setting or a configured default, and a worktree can place edits outside the main checkout. Sandbox ceilings restrict where Codex commands can write and whether they can access the network. Unsandboxed execution is unavailable unless explicitly permitted by the configured ceiling.

The operating-system sandbox applies to commands run by Codex, not to MCP or plugin tools that run as separate processes. The server does not automatically inherit those tools unless its configuration allows them. Linux and Windows behavior has not been measured in the repository's documented safety measurements, and sandboxed reads may be stricter on Windows. This project is independent and is not affiliated with OpenAI or Anthropic.

_Full upstream README: https://allmcps.com/mcp/codex-subagent/readme_