MCP Subagent Server

Name: MCP Subagent Server
Author: dvcrn

@dvcrn

Repository

About MCP Subagent Server

MCP for letting agents delegate tasks to sub-agents (Claude Code, Aider, Q)

#mcp-server #sub-agent #task-delegation

Basic information

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "subagent": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-server-subagent"
      ]
    }
  }
}

Tools

No tools detected

We auto-extract tools from the README. The maintainer can list them under a ## Tools heading to populate this section.

Overview

What is MCP Subagent Server?

MCP Subagent Server is a Model Context Protocol (MCP) server that allows dispatching tasks to sub‑agents such as Claude Code, Amazon Q, or Aider. It enables a “planning” agent to delegate tasks to “executor” agents, facilitating hierarchical agent workflows.

How to use MCP Subagent Server?

Install via npx -y mcp-server-subagent or run the local build, then add the server to your MCP configuration file (e.g., ~/.aws/amazonq/mcp.json). After configuration, the parent agent can invoke tools like run_subagent_q, run_subagent_claude, check_subagent_status, get_subagent_logs, and the bi‑directional communication tools (ask_parent, reply_subagent, check_message_status).

Key features of MCP Subagent Server

Configure and run sub‑agents through MCP tools
Each sub‑agent exposes four tools for execution, status, logs, and updates
Bi‑directional communication: sub‑agents can ask questions and wait for parent replies
Supports the ‘q’ (Amazon Q CLI) and ‘claude’ (Claude CLI) sub‑agents out of the box
Real‑time streaming logs for monitoring sub‑agent execution
Easily extensible: add new sub‑agents by modifying the SUBAGENTS object in source code

Use cases of MCP Subagent Server

A planning agent delegates code‑modification tasks to a Claude CLI sub‑agent
An orchestrator runs queries against Amazon Q CLI and retrieves the results
A parent agent receives clarifying questions from a sub‑agent during long‑running operations
Monitoring and logging all sub‑agent runs for auditing or debugging
Coordinating multiple specialized executors in a single MCP‑enabled workflow

FAQ from MCP Subagent Server

Which sub‑agents are supported by default?

By default, the server includes the ‘q’ sub‑agent (Amazon Q CLI) and the ‘claude’ sub‑agent (Claude CLI).

How do I add a new sub‑agent?

Edit the SUBAGENTS object in src/index.ts – provide a name, command, arguments, and description, then rebuild. The new sub‑agent’s tools will be automatically generated.

How does bi‑directional communication work?

Sub‑agents use ask_parent to pose a question; the parent polls status or uses reply_subagent to answer; the sub‑agent retrieves the answer with check_message_status. The system uses a message‑passing model with acknowledgment.

What are the best practices for polling?

Use sleep 30 between status checks and message polling to avoid overwhelming the system. Ask specific, actionable questions and respond promptly to keep execution flowing.

Where are run logs stored?

All sub‑agent runs are logged to a logs directory with three files per run: <run-id>.log (real‑time output), <run-id>.prompt.md (the prompt), and <run-id>.meta.json (metadata including communication messages).