Skip to main content
Glama
claude-subagents-mcp

claude-subagents-mcp

by jordankzf

Use Claude subagents in Codex

A Python stdlib MCP server that delegates tasks to up to four parallel Claude subagents, with optional workspace file access and per-agent model and reasoning effort configuration. Other stdio MCP clients are also supported.

A tasteful diagram of a central controller node linked to four modular agents, each representing an independent Claude subagent working in parallel

Features

  • Parallel agent orchestration -- spawn up to four concurrent Claude subagents, each with its own task, model, and reasoning effort

  • Async spawn/wait pattern -- agents run in background worker processes; your main session continues working while they do

  • Cursor-based result delivery -- wait on multiple agents at once, receive each result exactly once, and track delivery with cursors

  • Workspace file access -- optionally grant agents scoped read or read/write access to a directory, with path restrictions that exclude .git, .codex, and .agents

  • Follow-up messages -- send corrections or additional instructions to running or idle agents without restarting their context

  • Model and effort selection -- choose any model advertised by your proxy, with configurable reasoning effort that adapts automatically for models that lack effort support

  • Durable task state -- agent progress persists to disk across MCP client restarts; recover tasks by ID or optional request key

  • Deduplication -- identical in-flight tasks are detected and reused, preventing accidental double-spawns after transport failures

  • No external dependencies -- runs on Python 3.11+ using only the standard library

  • Batch file reads -- agents can read up to 16 files in a single tool call, reducing round trips during source review

Related MCP server: agentmux

Requirements

  • Python 3.11 or later

  • An Anthropic-compatible API endpoint (local proxy or https://api.anthropic.com)

Installation

Clone the repository and install:

git clone https://github.com/jordankzf/claude-subagents-mcp.git
cd claude-subagents-mcp
python -m pip install .

You can also install directly from GitHub:

pip install git+https://github.com/jordankzf/claude-subagents-mcp.git

This project is not published to PyPI.

Quickstart

After installation, the server is available as a console command:

claude-subagents-mcp

Or run it directly:

python claude_subagents_mcp.py

The server communicates over stdio using the MCP JSON-RPC protocol. Configure your MCP client to launch the command and connect over stdin/stdout.

Codex Configuration

Create or edit your Codex MCP configuration to include the server. See examples/codex-config.toml for a working template:

[mcp_servers.claude-subagents]
command = "claude-subagents-mcp"
tool_timeout_sec = 65
env_vars = ["ANTHROPIC_API_KEY"]

[mcp_servers.claude-subagents.env]
ANTHROPIC_BASE_URL = "https://api.anthropic.com"
CLAUDE_DEFAULT_MODEL = "claude-fable-5-1"
CLAUDE_DEFAULT_REASONING_EFFORT = "medium"

The env_vars array forwards ANTHROPIC_API_KEY from your shell environment into the Codex process, which passes it through to the MCP server. The env table sets additional configuration directly. Never commit secrets to the repository or to this file; set ANTHROPIC_API_KEY in your environment instead.

You can also configure all settings through environment variables in your shell before launching Codex:

export ANTHROPIC_API_KEY="your-api-key"
export ANTHROPIC_BASE_URL="https://api.anthropic.com"
export CLAUDE_DEFAULT_MODEL="claude-fable-5-1"
export CLAUDE_DEFAULT_REASONING_EFFORT="medium"

Environment Variables

Variable

Default

Description

ANTHROPIC_API_KEY

(none, recommended)

API key for the configured Anthropic-compatible endpoint

ANTHROPIC_PROXY_API_KEY

(none)

Legacy alias for ANTHROPIC_API_KEY

ANTHROPIC_BASE_URL

http://localhost:8317

Base URL of the API endpoint. Configurable to any Anthropic-compatible service including https://api.anthropic.com. Remote HTTP is rejected; only HTTPS is accepted outside loopback addresses

CLAUDE_DEFAULT_MODEL

claude-fable-5-1

Default model ID passed to the endpoint

CLAUDE_DEFAULT_REASONING_EFFORT

medium

Default reasoning effort: default, low, medium, high, xhigh, or max

CLAUDE_AGENT_STATE_DIR

(platform default)

Directory for persisted task state. On Windows: %LOCALAPPDATA%\claude-subagents-mcp\tasks. On Linux/macOS: ~/.local/share/claude-subagents-mcp/tasks

Tools

Tool

Description

spawn_claude_agent

Spawn an independent subagent with a task, optional workspace, model, and effort. Returns an agent ID immediately

get_claude_agent

Read agent status, activity, changed files, and result. Optionally wait up to 10 seconds

wait_claude_agents

Wait for the first of up to four agents to finish (max 50 seconds). Returns full result with cursors for once-only delivery

send_claude_message

Send a follow-up to a running or idle agent. Running agents receive it at the next response boundary; idle agents resume

cancel_claude_agent

Cancel an active task. Prevents further file operations; already-pending API requests may complete in the background

list_claude_agents

Recovery only: compact summaries of recent agents. Normally use the ID from spawn directly with wait_claude_agents

list_claude_models

List models advertised by the proxy and current bridge defaults. Use when choosing a model, not before every spawn

ask_claude

Start a consultation and return an agent ID immediately. Collect the answer with wait_claude_agents or get_claude_agent. For workspace tasks use spawn_claude_agent

Model and Effort Selection

Each agent can target a specific model and reasoning effort level. The defaults are claude-fable-5-1 and medium, configurable through environment variables.

Available effort levels: default, low, medium, high, xhigh, max.

Setting effort to default omits the effort parameter from the API request entirely, letting the provider decide.

Automatic adaptation with reported adjustment: When a model is known not to support effort control (or when the proxy explicitly rejects it), inherited effort settings are automatically omitted. The server remembers which models lack effort support and omits the parameter on future requests. The adjustment is not silent: the configuration_note field in the response explains what was changed and why.

Explicit choices are honored or rejected clearly. If you explicitly set reasoning_effort on a spawn call and the model does not support it, the request fails with a clear error rather than changing your intent. This distinction between inherited defaults and explicit choices prevents surprising behavior.

Unknown model capabilities are not guaranteed. A model not yet tested for effort support will attempt the request as configured; if the provider rejects it and the effort was inherited, it retries once without effort and reports the adjustment. If the effort was explicit, the failure is reported.

Reliability and Limitations

  • Up to four concurrent agents. Additional spawns are rejected until an active agent completes or is cancelled.

  • Spawn and wait timeouts. wait_claude_agents accepts up to 50 seconds. Individual tasks default to 300 seconds (configurable 10 to 900).

  • Cursor-based delivery. Each terminal result is delivered exactly once per wait call. Pass the returned cursors object back on subsequent waits to avoid re-receiving completed results.

  • No shell, browser, or native panel access. Subagents can only use the file tools provided by the server (list, read, batch read, write). They cannot execute commands, open browsers, or display UI.

  • Workspace path restrictions are not an OS sandbox. File access is scoped to the provided workspace directory through path validation, but this is application-level enforcement, not kernel-level isolation.

  • Prompts and file contents are sent to the configured endpoint. Be mindful of what you include in tasks and workspaces.

  • Task histories are stored locally and may contain sensitive material. The state directory should be treated accordingly.

  • CI covers Windows, Linux, and macOS with Python 3.11 through 3.13. Windows has additional live testing.

  • This is an initial 0.1.0 release, not a production guarantee. Expect rough edges.

Examples

Spawn and wait for a single agent

spawn_claude_agent(task="Analyze the error handling in src/api.py", workspace="/path/to/project")
  -> { agent_id: "abc123...", status: "queued" }

wait_claude_agents(agent_ids=["abc123..."])
  -> { results: [{ agent_id: "abc123...", status: "completed", result: "..." }], cursors: {...} }

Parallel agents with cursor tracking

spawn_claude_agent(task="Review authentication module", workspace="/project", task_name="auth-review")
spawn_claude_agent(task="Review database layer", workspace="/project", task_name="db-review")

wait_claude_agents(agent_ids=["id1", "id2"], timeout_seconds=45)
  -> { results: [first completed], pending: [still running], cursors: {"id1": 3} }

wait_claude_agents(agent_ids=["id1", "id2"], timeout_seconds=45, cursors={"id1": 3})
  -> { results: [second completed], cursors: {"id1": 3, "id2": 5} }

Ask and wait

ask_claude(prompt="Summarize the key differences between these two approaches")
  -> { agent_id: "def456...", status: "queued" }

wait_claude_agents(agent_ids=["def456..."])
  -> { results: [{ agent_id: "def456...", status: "completed", result: "..." }], cursors: {...} }

Follow-up message

send_claude_message(agent_id="abc123...", message="Also check for SQL injection risks")
wait_claude_agents(agent_ids=["abc123..."])

Testing

The test suite uses unittest and does not make live API calls:

python -m unittest discover -s tests

CI runs this suite on Windows, Linux, and macOS across Python 3.11, 3.12, and 3.13.

Contributing

See CONTRIBUTING.md for guidelines on reporting issues, suggesting features, and submitting pull requests.

Security

See SECURITY.md for the security model, known boundaries, and responsible disclosure guidance.

License

MIT -- Copyright 2026 jordankzf

Available Tools

8 tools
ask_claudeA

Start a Claude consultation and return an agent ID immediately. A queued/running result is NOT a timeout. Collect the answer using get_claude_agent; never resubmit just because it is pending. For workspace work use spawn_claude_agent.

Inputs: prompt (required), model, messages, max_tokens, +1 more.

cancel_claude_agentA

Cancel a delegated task. Prevents subsequent file operations; an already pending proxy request may finish in the background. Existing edits are retained.

Inputs: agent_id (required).

get_claude_agentA

Read Claude agent status, recent activity, changed files, and final result. Optionally wait up to 10 seconds. Tasks persist across Codex restarts.

Inputs: agent_id (required), wait_seconds.

list_claude_agentsA

Recovery only: compact recent agent summaries, without full reports. Normally use the ID returned by spawn directly with wait_claude_agents.

Inputs: no named parameters.

list_claude_modelsA

List model IDs advertised by the local proxy and current bridge defaults. Use when choosing a different model, not before every spawn. Effort support varies by model.

Inputs: no named parameters.

send_claude_messageA

Send a follow-up to a Claude subagent. Running agents receive it at the next model-response boundary; idle agents resume with existing context. Returns promptly. Wait on the same agent ID for results.

Inputs: message (required), agent_id (required).

spawn_claude_agentA

Spawn an independent Claude subagent. Save the returned ID, continue your own work, then call wait_claude_agents directly. No listing step is needed. No shell or browsing tools.

Inputs: task (required), model, max_steps, task_name, +6 more.

wait_claude_agentsA

Wait for the first of up to four specified Claude agents to finish or fail; returns its full result directly. No list/get cycle. Save returned cursors to avoid receiving the same result twice. Timeout means work remains pending.

Inputs: agent_ids (required), cursors, timeout_seconds.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 8 tools

    Disambiguation4/5

    Most tools have clearly distinct roles: spawn, wait, get, cancel, send, and list models are well separated. The main possible confusion is between ask_claude and spawn_claude_agent, but the descriptions explicitly distinguish consultation from workspace subagent work.

    Naming Consistency4/5

    The dominant verb_noun pattern is consistent (spawn_claude_agent, cancel_claude_agent, get_claude_agent, list_claude_models). Minor deviations include ask_claude lacking a noun and singular/plural inconsistency between agent and agents.

    Tool Count5/5

    Eight tools is well-scoped for managing the Claude subagent lifecycle: spawn, wait, get, cancel, message, list models, ask, and a recovery list. Each tool has a clear purpose without feeling bloated or thin.

    Completeness4/5

    The core lifecycle is well covered: spawning, waiting, polling, canceling, and follow-up messaging are all present. Minor gaps remain, such as no direct tool for listing all active agents or waiting on more than four at once, but these are workable limitations.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Enables any MCP host to delegate work to multiple coding-agent CLIs such as Codex, Claude Code, and Antigravity as subagents, preserving native sessions and supporting team-based supervision and agent-to-agent messaging.
      17
      9 npm
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables users to delegate coding tasks in a chosen project to the official Codex and Claude CLI agents from within an existing chat, then convene a council of configured models to gather independent opinions and review the resulting files and test runs. It also manages multi-provider API connections, model catalogs, and per-task token, time, and cost limits.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables Claude and Codex agents to delegate implementation, testing, research, or review tasks to each other through local MCP tools, while supporting persistent sessions, isolated editing workspaces, and reviewed integration. It also allows progress tracking, cancellation, model selection, and management handoff between providers.
      2
      MIT