mcp -subagent

This MCP server implements a sub-agent framework that lets a planning or coordinating agent delegate tasks to one or more executor sub-agents (such as Amazon Q or Claude). Each sub-agent exposes a set of tools to run a task, monitor progress, fetch logs, and update status. In addition, there is a bi-directional message system that allows the sub-agent to ask questions to its parent agent during execution and receive replies, with status polling support to retrieve responses. Typical workflows involve issuing a run_subagent_q or run_subagent_claude command with an input string, then periodically checking status and logs, and finally updating the sub-agent status with a summary once the task completes. The system also supports asking for parent guidance mid-run and receiving targeted responses via check_message_status and reply_subagent.

Available sub-agent tools include:

• run_subagent_q: Run a query through the Amazon Q CLI with a provided input string. Returns a runId for status/log retrieval.
• run_subagent_claude: Run a query through the Claude CLI with a provided input string. Returns a runId for status/log retrieval.
• check_subagent_status: Check the status and metadata of a given runId.
• get_subagent_logs: Retrieve the complete logs for a given runId.
• update_subagent_status: Update the run’s status (e.g., running, success, error, completed) and optionally include a summary.
• ask_parent: Sub-agent asks a question to the parent agent; returns a messageId and polling instructions.
• reply_subagent: Parent replies to a specific messageId for a given runId.
• check_message_status: Check the status of a message and fetch any available answer.

Bi-directional communication is supported via ask_parent, reply_subagent, and check_message_status, enabling real-time guidance while sub-agents execute. Real-time streaming logs provide visibility into sub-agent activity as it runs.

Prerequisites:\n- Node.js (LTS) and npm installed on the host. The server is designed to run as a Node-based MCP sub-agent.\n- Optional: npx is available with npm (usually installed with Node).\n\nInstall and run within your environment:\n1) Ensure Node.js is installed. \n2) Start or install the subagent MCP server via your preferred method (npm/pip/containers as appropriate). A typical approach is to use npx to run the subagent MCP server:\n\nbash\n# Using npx (preferred if you want to fetch the latest version)\nnpx -y mcp-server-subagent\n\n\nAlternatively, if you have a local build, you can run the built server directly via Node:\nbash\n# If you built and have an index.js or build/index.js, run:\nnode /ABSOLUTE/PATH/TO/mcp-server-subagent/build/index.js\n\n\n3) Create or edit your MCP configuration file (e.g., ~/.aws/amazonq/mcp.json) to reference the subagent as shown in the examples.\n4) Ensure the MCP configuration is picked up by your MCP runner or environment (the exact path may depend on your setup).\n\nPrerequisites recap:\n- Node.js and npm installed.\n- Access to either npx or a local build of the mcp-server-subagent.\n- A suitable MCP runtime environment to load ~/.aws/amazonq/mcp.json (or equivalent).\n

Tips and caveats:\n- The MCP server expects a configuration entry named 'subagent' under mcpServers, with a command and arguments that initialize the sub-agent server. The README examples show two common formats (npx and local Node path). Adapt paths and package names to your environment.\n- Logs for sub-agent runs are stored under a logs directory, with one file per run (e.g., <run-id>.log). Ensure the process has permission to write to this directory.\n- When using bi-directional communication, consider polling intervals to avoid overloading the system (e.g., sleep between status or message checks).\n- You can extend SUBAGENTS in src/index.ts to add new sub-agents with their own commands, arguments, and descriptions.\n- If you run multiple sub-agents, ensure runIds are unique and that environment variables (like credentials for Q or Claude CLI) are properly configured in the runner environment.\n- For production, consider containerizing the sub-agent server and pinning versions of the CLI tools you rely on (q CLI, Claude CLI) to stable versions.