mcp-server-subagent

mcp-server-subagent

3.2

If you are the rightful owner of mcp-server-subagent and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The MCP Subagent Server is a Model Context Protocol server designed to facilitate task delegation from planning agents to executor sub-agents.

MCP Subagent Server

This is a Model Context Protocol (MCP) server that allows dispatching of tasks to sub-agent (like Claude Code, Q or Aider)

The purpose of this MCP is to allow a "planning" agent to delegate tasks to "executor" agents

Features

  • Configure and run sub-agents through MCP tools
  • Each sub-agent exposes three tools:
    • run_subagent_<n>: Runs the sub-agent with provided input
    • check_subagent_status: Allows the agent to check on the status of a sub-agent
    • get_subagent_logs: Retrieves the logs of a sub-agent run
    • update_subagent_status: Updates the status and adds a summary of a previous run
  • Bi-directional communication: Sub-agents can ask questions to parent agents during execution using ask_parent, parents can reply using reply_subagent, and sub-agents can check for replies using check_message_status
  • Currently supports the 'q' sub-agent (Amazon Q CLI) and 'claude' sub-agent (Claude CLI)
  • Real-time streaming logs for monitoring sub-agent execution

Installation

Add this to your MCP configuration file (~/.aws/amazonq/mcp.json):

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

Or if you installed it locally:

{
  "mcpServers": {
    "subagent": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/mcp-server-subagent/build/index.js"]
    }
  }
}

Available Tools

Sub-agent Execution Tools

  • run_subagent_q: Run a query through the Amazon Q CLI

    • Parameters: input (string) - The query to send to Amazon Q
    • Returns: A run ID that can be used to check the status or get logs

  • run_subagent_claude: Run a query through the Claude CLI

    • Parameters: input (string) - The query to send to Claude
    • Returns: A run ID that can be used to check the status or get logs

  • check_subagent_status: Check the status of a previous run

    • Parameters: runId (string) - The UUID of the run to check
    • Returns: The status and metadata of the run

  • get_subagent_logs: Get the logs of a previous run

    • Parameters: runId (string) - The UUID of the run to get logs for
    • Returns: The complete logs of the run

  • update_subagent_status: Update the status and add a summary of a previous run

    • Parameters:
      • runId (string) - The UUID of the run to update
      • status (string) - The new status to set (one of: "success", "error", "running", "completed")
      • summary (string, optional) - A summary or result message to include with the status update
    • Returns: The updated status and metadata of the run
Bi-directional Communication Tools

  • ask_parent: Enables sub-agents to ask questions to the parent agent

    • Parameters: runId (string), question (string)
    • Returns: Message ID and polling instructions

  • reply_subagent: Enables parents to reply to sub-agent questions

    • Parameters: runId (string), messageId (string), answer (string)
    • Returns: Confirmation of the reply

  • check_message_status: Check message status and retrieve replies

    • Parameters: runId (string), messageId (string)
    • Returns: Message details and answer if available

Bi-directional Communication

The MCP Subagent Server supports bi-directional communication between parent agents and sub-agents through a message passing system. This allows sub-agents to ask questions during execution and receive guidance from the parent agent.

Communication Tools

  • ask_parent: Enables sub-agents to ask questions to the parent agent

    • Parameters:
      • runId (string) - The sub-agent's current run ID
      • question (string) - The question/message content
    • Returns: A message ID and instructions for polling the answer

  • reply_subagent: Enables parents to reply to specific questions from sub-agents

    • Parameters:
      • runId (string) - The sub-agent's run ID
      • messageId (string) - The ID of the message being replied to
      • answer (string) - The parent's reply content
    • Returns: Confirmation of the reply

  • check_message_status: Check the status of a specific message and retrieve replies

    • Parameters:
      • runId (string) - Run ID to check message status for
      • messageId (string) - Message ID to check status for
    • Returns: Message details and answer if available (acknowledges the message)

Example Workflow

Here's how bi-directional communication works in practice:

1. Sub-agent asks a question

The sub-agent uses the ask_parent tool during execution:

{
  "tool": "ask_parent",
  "arguments": {
    "runId": "abc-123-def",
    "question": "I found multiple config files. Which one should I modify: config.json or settings.yaml?"
  }
}

Response:

{
  "messageId": "msg-456-789",
  "instructions": "Poll for the answer using the 'check_message_status' tool with your runId and messageId. Since this could take a while for the parent to respond, use 'sleep 60' between calls to avoid spamming."
}
2. Parent checks sub-agent status

When the parent checks the sub-agent status, they'll see:

Status: waiting_parent_reply

Question awaiting reply (Message ID: msg-456-789):
  I found multiple config files. Which one should I modify: config.json or settings.yaml?
  (Asked at: 2025-01-15T10:30:00.000Z)
  To reply, use the 'reply_subagent' tool.

Note: This may take a while for the parent to respond. Use 'sleep 60' between status checks to avoid spamming.
3. Parent provides an answer

The parent uses the reply_subagent tool:

{
  "tool": "reply_subagent",
  "arguments": {
    "runId": "abc-123-def",
    "messageId": "msg-456-789",
    "answer": "Please modify config.json - it's the main configuration file. The settings.yaml is just for development overrides."
  }
}
4. Sub-agent retrieves the answer

The sub-agent polls for the answer using check_message_status:

{
  "tool": "check_message_status",
  "arguments": {
    "runId": "abc-123-def",
    "messageId": "msg-456-789"
  }
}

Response when answer is available:

{
  "messageId": "msg-456-789",
  "questionContent": "I found multiple config files. Which one should I modify: config.json or settings.yaml?",
  "answerContent": "Please modify config.json - it's the main configuration file. The settings.yaml is just for development overrides.",
  "messageStatus": "acknowledged_by_subagent",
  "hasAnswer": true
}

The sub-agent can then continue execution with the parent's guidance.

Best Practices

  • Polling Frequency: Use sleep 30 between status checks and message polling to avoid overwhelming the system
  • Question Clarity: Ask specific, actionable questions that help guide the task execution
  • Timely Responses: Parents should monitor sub-agent status regularly to provide timely guidance
  • Message Acknowledgment: The check_message_status tool automatically acknowledges messages when answers are retrieved

Adding New Sub-agents

To add a new sub-agent, modify the SUBAGENTS object in src/index.ts:

const SUBAGENTS = {
  q: {
    name: "q",
    command: "q",
    getArgs: () => ["chat", "--trust-all-tools", "--no-interactive"],
    description: "Run a query through the Amazon Q CLI",
  },
  claude: {
    name: "claude",
    command: "claude",
    getArgs: () => [
      "--print",
      "--allowedTools",
      "Bash(git*) Bash(sleep*) Edit Write mcp__subagent__update_subagent_status",
      "--mcp-config",
      JSON.stringify(mcpConfig),
    ],
    description: "Run a query through the Claude CLI",
  },
  // Add your new sub-agent here
  newagent: {
    name: "newagent",
    command: "your-command",
    getArgs: () => ["--some-flag", "--other-flags"],
    description: "Description of your new agent",
  },
};

Logs

All sub-agent runs are logged to the logs directory with two files per run:

  • <run-id>.log: Contains the real-time output logs
  • <run-id>.prompt.md: Contains the prompt passed to the agent
  • <run-id>.meta.json: Contains metadata about the run (including communication messages)