MCP Subagent Server

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).