Subagent MCP

Subagent MCP gives Codex and other stdio MCP clients one local lifecycle for delegating work to external coding-agent harnesses. Each adapter uses the provider's native harness while Subagent MCP keeps status, sessions, input, and results consistent for the client.

The project and repository are named Subagent MCP. The Python distribution and command are subagent-harness-mcp because the shorter package name was already taken.

Preview: 0.1.0a3 targets Windows. The local MCP, deterministic adapter, package, and localhost UI are usable. Live Claude Code work remains gated until the exact native-harness and no-overage canary passes.

Install

Install uv first if you do not already have it:

winget install --id=astral-sh.uv -e

Then install the pinned preview and connect it to Codex:

uv tool install subagent-harness-mcp==0.1.0a3
codex mcp add subagent-mcp -- subagent-harness-mcp serve

Start a new Codex task after registration. You can confirm the installation at any time:

subagent-harness-mcp --version
codex mcp list

If 0.1.0a3 has not reached PyPI yet, install the current checkout instead:

uv tool install .

Open the local UI

subagent-harness-mcp ui

This opens a temporary browser session on localhost for settings, health, and read-only activity. It is not an agent chat window, and the server stops when the command exits.

How it fits together

flowchart LR
    C["Codex or another MCP client"] -->|"stdio MCP"| S["Subagent MCP"]
    U["Browser UI<br/>localhost only"] --> S
    S --> D[("Local config and activity")]
    S --> L["Normalized subagent lifecycle"]
    L --> F["Deterministic adapter"]
    L --> N["Native harness adapters"]
    N --> H["Claude Code"]
    N -.-> X["Future harnesses"]

The service owns lifecycle state, idempotency, redaction, leases, and circuits. Adapters translate that contract to a native harness and do not write shared state directly. See the architecture for details.

What works in this preview

Green deterministic tests prove the local contract; they do not prove that a live provider is ready.

Other MCP clients

Point any stdio-compatible MCP client at the installed command:

{
  "command": "subagent-harness-mcp",
  "args": ["serve"]
}

The MCP exposes versioned runtime, project-trust, agent-lifecycle, and workspace tools. Public schemas live in schemas/.

Safety and billing

• Subagent MCP never enables usage credits or changes billing settings.
• Managed provider work fails closed on missing identity, model, workspace, session, or no-overage evidence; it does not silently choose a fallback.
• Provider model IDs and reasoning settings remain native, opaque values.
• Product data stays in explicit local config, state, and data roots. Optional client registration uses the client's official command and verifies the exact entry instead of directly rewriting unrelated configuration.
• Native transcripts remain owned by the native harness. Treat agent output as untrusted advice and verify it before applying changes.

Read the full threat model and report vulnerabilities privately as described in SECURITY.md.

Development

CONTRIBUTING.md contains the deterministic test workflow and adapter guidelines. Subagent MCP is released under the MIT License.