Advertise
MCP.so
Sign In

MCP Subagent Server

@dvcrn

Repository

Basic information

Category

Other

License

AGPL-3.0 license

Transports

stdio

Author

dvcrn

About MCP Subagent Server

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

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

MCP Subagent Server config

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

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

MCP Subagent Server tools

8

Delegates the given task to a q subagent as an asynchronous sub-task. This creates a new agent instance that will handle the provided input independently and report back its results. The task can be short or long-running. Use check_subagent_status with the returned runId to monitor progress, as completion may take some time. Synonyms: Run subtask, run sub-agent, delegate task, delegate sub-task. Run a query through the Amazon Q CLI

Delegates the given task to a claude subagent as an asynchronous sub-task. This creates a new agent instance that will handle the provided input independently and report back its results. The task can be short or long-running. Use check_subagent_status with the returned runId to monitor progress, as completion may take some time. Synonyms: Run subtask, run sub-agent, delegate task, delegate sub-task. Run a query through the Claude CLI

Check the status of a subagent run. Since sub-agents can take a while it is recommneded to wait at least 30 or 60 seconds (`sleep 30`) in between polling intervals.

Get the logs of a subagent run. This can be VERY long, so only use this tool if instructed. Requires only the runId.

Update the status and summary of a subagent run. This tool is meant to be used from sub-agents, not the main agent. Requires runId and status.

Enables the subagent to ask a question to the parent agent.

Enables the parent to reply to a specific question from a subagent.

Check the status of a specific message and retrieve the reply if available. This will acknowledge the message if it has been replied to.

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

Frequently asked questions

1

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

2

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.

3

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.

4

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.

5

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

Comments

More Other MCP servers

Figs, Relationship Expert

Figs O'Sullivan, LMFT

Couples therapist Figs O'Sullivan (LMFT, 17 years, endorsed by Sue Johnson, creator of EFT) inside your AI. Ask relationship questions answered from his clinical writing, name the pattern in a fight, get a three-step rep

Codelf

unbug

A search tool helps dev to solve the naming things problem.

14.2K

ICSS

chokcoco

不止于 CSS

20.7K

Glasswarp

Glasswarp

See and control a real Windows PC you own — from any MCP client, locally or remotely. Observe (UIA + screenshots), click/type/drag/scroll, launch apps, owner Live View. BYOH: your machine, your key.

Klarix Intelligence Engine

Klarix

B2B competitive intelligence, live sales battlecards, 5-axis ICP prospect fit scoring, and tech stack teardowns over MCP and REST with cited public-web evidence.

Advertise