claude-subagents-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@claude-subagents-mcp Spawn four subagents to review the code, tests, docs, and security of this repo."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.

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.agentsFollow-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.gitThis project is not published to PyPI.
Quickstart
After installation, the server is available as a console command:
claude-subagents-mcpOr run it directly:
python claude_subagents_mcp.pyThe 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 |
| (none, recommended) | API key for the configured Anthropic-compatible endpoint |
| (none) | Legacy alias for |
|
| Base URL of the API endpoint. Configurable to any Anthropic-compatible service including |
|
| Default model ID passed to the endpoint |
|
| Default reasoning effort: |
| (platform default) | Directory for persisted task state. On Windows: |
Tools
Tool | Description |
| Spawn an independent subagent with a task, optional workspace, model, and effort. Returns an agent ID immediately |
| Read agent status, activity, changed files, and result. Optionally wait up to 10 seconds |
| Wait for the first of up to four agents to finish (max 50 seconds). Returns full result with cursors for once-only delivery |
| Send a follow-up to a running or idle agent. Running agents receive it at the next response boundary; idle agents resume |
| Cancel an active task. Prevents further file operations; already-pending API requests may complete in the background |
| Recovery only: compact summaries of recent agents. Normally use the ID from spawn directly with |
| List models advertised by the proxy and current bridge defaults. Use when choosing a model, not before every spawn |
| Start a consultation and return an agent ID immediately. Collect the answer with |
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_agentsaccepts 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
cursorsobject 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 testsCI 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 toolsask_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
Scored across 8 tools
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.
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.
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.
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
Related MCP Connectors
- aXDeprecatedio.github.ax-platform
Agent-native collaboration network: orchestrate a team of long-running agents from any MCP client.
Multiplayer for the coding agents your team already uses: shared tasks, decisions, skills and tools.
Shared memory and mail for your AI agents. Verified with Claude Code; other MCP clients in testing.
Your AI apps as one team: hand work to Codex or Claude Code on your Mac, with a shared logbook.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables spawning and managing multiple Claude Code agents in parallel with model selection, live tracking via a kanban dashboard, and consolidated answers back in the chat.MIT
- AlicenseBqualityBmaintenanceEnables 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.179 npmApache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables 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
- AlicenseNot gradedqualityCmaintenanceEnables 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.2MIT