codex-subagents-mcp-server by hasandz - MCP Server

Codex Subagents MCP Server

A Model Context Protocol (MCP) server that fronts a curated set of Codex personas. It launches persistent Codex conversations for each agent, routes /mcp delegations, and records per-request logs so you can iterate on multi-agent workflows with confidence.

Highlights

Parallel delegations. delegate_batch fans out tasks concurrently and returns colour-coded status headers for every agent.
Safe defaults. The driver automatically clears Codex's MCP registry, extends startup/tool timeouts, and defaults to in-memory persistence so a single config entry "just works".
Observable runs. Each delegation stores stdout/stderr and event history under .codex-subagents/logs/<request-id>/, making triage straightforward.

Requirements

Node.js 20.11+
Codex CLI 0.42+ (installed and logged in)

Install & Build

npm install
npm run build

Smoke Test (Optional)

npm run smoke

The script launches the server with the bundled sample agents (agents/) and issues a delegate_batch. Inspect .codex-subagents/logs/ afterwards to see the generated summaries.

Use with Codex CLI

Add the server to ~/.codex/config.toml with a single npx invocation. Include --yes so npm skips the interactive install prompt and --quiet so npm keeps stdout clean (run once in a shell if you want to warm the cache first). The package ships with a starter set of personas under agents/, so you can try it without any extra setup:

docs – documentation specialist who turns repo context into clear guides.
debugger – systems debugger focusing on repro steps and mitigation checklists.
review – code reviewer looking for regressions and test gaps.
orchestrator – triage lead who routes tasks to the right specialist.
backend – senior backend engineer optimising APIs, storage, and resilience.
frontend – senior frontend engineer balancing UX, performance, and accessibility.
design – UI/UX expert offering product discovery and polish recommendations.
architect – principal architect framing long-term systems strategy.

[mcp_servers.subagents]
command = "npx"
args = ["--yes", "--quiet", "codex-subagents-mcp-server@latest"]

Restart Codex and run /mcp. You should see subagents.delegate and subagents.delegate_batch available. Try:

/mcp subagents.delegate {"agent":"docs","task":"Give me two tips for onboarding to this repo."}
/mcp subagents.delegate_batch {"items":[{"agent":"docs","task":"Summarise src/ in three bullets."},{"agent":"debugger","task":"List two quick checks when the server fails to start."}]}

Each response begins with a coloured badge (or a plain label if your terminal lacks ANSI support) showing the agent name and a short summary.

Tip: run npx --yes --quiet codex-subagents-mcp-server@latest -- --help once from a normal shell to pre-populate the npm cache so your first Codex launch does not wait on downloads.

Use your own agents

Point the server at a directory that contains Markdown or JSON manifests using either a CLI flag or an environment variable:

[mcp_servers.subagents]
command = "npx"
args = [
  "--yes",
  "--quiet",
  "codex-subagents-mcp-server@latest",
  "--agents-dir",
  "/absolute/path/to/your/agents"
]

Or set CODEX_SUBAGENTS_DIR=/absolute/path/to/your/agents before the server starts. Manifests follow the same format as the bundled examples in agents/.

Optional Configuration

Enable SQLite persistence – set CODEX_SUBAGENTS_DISABLE_PERSISTENCE=0 before launching the server. The database lives under .codex-subagents/state/state.sqlite by default.
Custom Codex arguments – set CODEX_SUBAGENTS_CODEX_ARGS (JSON array) or CODEX_SUBAGENTS_CODEX_ENV (JSON object) to extend the spawned codex mcp process.
Rollout recorder permissions – if Codex cannot initialise its rollout recorder, point CODEX_ROLLOUT_DIR to a writable directory (e.g. mkdir -p ~/.codex/rollouts && export CODEX_ROLLOUT_DIR=~/.codex/rollouts).
Additional workspace roots – set CODEX_SUBAGENTS_EXTRA_ROOTS (comma- or semicolon-separated list of absolute paths) so roots/list responses include extra directories beyond the current workspace.

Logs & Persistence

Logs – every delegation writes stdout/stderr under .codex-subagents/logs/<request-id>/<step-id>/.
Persistence – in-memory by default. Enable SQLite via CODEX_SUBAGENTS_DISABLE_PERSISTENCE=0 for durable request/step history. Override locations with CODEX_SUBAGENTS_DB, CODEX_SUBAGENTS_STATE_DIR, or CODEX_SUBAGENTS_LOG_DIR.

Repository Structure

agents/             # Bundled personas shipped with the npm package
scripts/            # Utility scripts (e.g. smoke-delegations.mjs)
src/                # MCP server implementation
  codex/            # Codex driver and JSON-RPC client
  persistence/      # SQLite + in-memory repositories
  terminal/         # Presentation helpers (coloured headers)
docs/               # Design notes and supplementary guides

Local Development

npm run dev – rebuild on change using tsup watch.
npm run lint – ESLint with TypeScript rules.
npm run typecheck – tsc --noEmit.
npm run test – placeholder for future Vitest suites.
npm run smoke – launch the sample agents and issue a delegate_batch.

Contributing

Contributions are welcome! Please read for the workflow and coding standards. All contributions are licensed under the MIT License.