Sub-Agent MCP

Overview

Sub-Agent MCP is an MCP server that enables LLM delegation and sub-agent orchestration via MCP. When a parent agent needs to focus on a specific sub-task, it can spawn a sub-agent through Sub-Agent MCP — each with its own context, tools, and system prompt — and receive the result back through the MCP tool interface.

Featured on Show HN as "Sub-Agent MCP: LLM delegation and sub-agent orchestration via MCP".

The design pattern is familiar to anyone who's built multi-agent systems: a parent agent delegates complex work to specialized sub-agents. Sub-Agent MCP abstracts this into an MCP server so that any MCP client (Claude Code, Cursor, Zed) can use it as a building block.

Features

• Sub-agent spawning: any MCP client can spawn a sub-agent with a custom system prompt and tools
• Synchronous and asynchronous: wait for result, or fire-and-forget with callback
• Tool scoping: sub-agents get only the tools you specify
• Context isolation: sub-agents don't see the parent's conversation history
• Result streaming: sub-agent responses can stream back to the parent
• Local LLM or API: works with any model provider
• Session management: multiple sub-agents can run in parallel

Installation

# Install the MCP server
npm install -g @sub-agent-mcp/server

# Or run directly
npx -y @sub-agent-mcp/server

Configuration

{
  "mcpServers": {
    "sub-agent": {
      "command": "npx",
      "args": ["-y", "@sub-agent-mcp/server"],
      "env": {
        "SUB_AGENT_PROVIDER": "anthropic",
        "SUB_AGENT_MODEL": "claude-sonnet-4-6",
        "SUB_AGENT_API_KEY": "${ANTHROPIC_API_KEY}"
      }
    }
  }
}

Available Tools

Tool	Description
spawn_sync	Spawn a sub-agent, wait for result, return
spawn_async	Spawn a sub-agent, return session ID immediately
send_message	Send a follow-up message to a running sub-agent
get_result	Poll for a running sub-agent's result
cancel	Cancel a running sub-agent
list_active	List currently active sub-agents

Example Usage

Spawn a synchronous sub-agent

Ask Claude: "Use a sub-agent to write unit tests for auth.ts."

{
  "tool": "spawn_sync",
  "args": {
    "system_prompt": "You are a test writer. Write thorough unit tests for the given code.",
    "message": "Write unit tests for auth.ts at ./src/auth.ts",
    "tools": ["read_file", "write_file"],
    "timeout_seconds": 300
  }
}

Response:

{
  "status": "completed",
  "result": "Created 12 unit tests in ./src/auth.test.ts. Coverage: 87%.",
  "duration_ms": 4230,
  "model_used": "claude-sonnet-4-6"
}

Spawn parallel sub-agents

{
  "tool": "spawn_async",
  "args": {
    "system_prompt": "You are a code reviewer. Identify issues.",
    "message": "Review ./src/auth.ts",
    "tools": ["read_file"]
  }
}

Then poll:

{
  "tool": "get_result",
  "args": { "session_id": "subagent-abc123" }
}

Orchestrator Pattern

The classic orchestrator-workers pattern becomes clean:

# Pseudocode — orchestrator agent uses Sub-Agent MCP
subagents = [
    mcp.spawn_async(system_prompt=REVIEWER_PROMPT, message=review_task),
    mcp.spawn_async(system_prompt=TESTER_PROMPT, message=testing_task),
    mcp.spawn_async(system_prompt=DOCS_PROMPT, message=docs_task),
]

results = [mcp.get_result(sid) for sid in subagents]
summary = synthesize(results)

Pros

• ✅ MCP-native delegation: any MCP client can spawn sub-agents
• ✅ Sync and async modes: blocking or fire-and-forget
• ✅ Tool scoping: sub-agents get only what you allow
• ✅ Context isolation: prevents context pollution between parent and sub-agents
• ✅ Parallel execution: spawn multiple sub-agents simultaneously
• ✅ Streaming support: long-running sub-agents can stream progress

Cons

• ❌ Tiny community: ~25 GitHub stars, single maintainer
• ❌ No persistence: sub-agent history is lost when the server restarts
• ❌ Single-model: sub-agents use the configured model, no per-agent model selection
• ❌ No built-in orchestration: you have to write the orchestration loop yourself
• ❌ No tool inheritance: sub-agents must declare tools explicitly

When to Use

Use Sub-Agent MCP when:

• You want to delegate work to specialist sub-agents from an MCP client
• You're building orchestrator-workers without adopting a full framework
• You need context isolation between parent and child agents
• You want parallel sub-agent execution for throughput

Prefer alternatives when:

• You need full framework features (state, checkpoints, memory) — use LangGraph
• You need persistence across restarts — use RunAgent or a framework
• You want automatic task decomposition — use an orchestrator pattern from a framework

Resources

• GitHub Repository
• Show HN discussion