sub-agents

Sub-Agents MCP Server lets you define task-specific AI agents (for example, a code-reviewer or a test-writer) inside markdown files and invoke them through common MCP backends like Cursor CLI, Claude Code, Gemini CLI, or Codex. Agents are loaded from a dedicated agents folder and executed via the selected execution engine through the MCP layer, enabling cross-tool reuse of the same agent definitions. This makes it possible to run the same agent across different MCP-enabled clients without recreating logic for each tool.

To use Sub-Agents, point your MCP configuration to the sub-agents MCP server and provide the absolute path to your agents folder via AGENTS_DIR. The AGENT_TYPE setting lets you optionally constrain or tailor agent behavior to the tool you’re using (for example, cursor for Cursor CLI, claude for Claude Code, gemini for Gemini CLI, or codex for Codex). Once configured, you can instruct your MCP-enabled client to invoke a specific agent by name, such as code-reviewer or test-writer, and the backend will load the corresponding markdown-based task description and run it against the chosen execution engine. This enables session management, structured agent outputs, and consistent error handling across tools.

Typical workflow: create or edit agent markdown files in your agents folder, configure AGENTS_DIR and AGENT_TYPE in your MCP config, restart your IDE or MCP client, and then issue a request like “Use the code-reviewer agent to review this file.” The MCP server handles loading the agent, running the appropriate backend CLI, and returning structured results back to your client.

Prerequisites:

• Node.js 20 or higher
• npm (comes with Node.js)
• An MCP-compatible tool (Cursor IDE, Claude Desktop, Windsurf, etc.)
• An absolute path folder containing your agent markdown files

Step 1: Install Node.js (if not already installed)

• Follow instructions at https://nodejs.org/ to install Node.js 20+.

Step 2: Prepare your agents directory

• Create a folder with agent markdown files (for example: /absolute/path/to/your/agents-folder).
• Each agent should be a markdown file named after the agent (e.g., code-reviewer.md).

Step 3: Configure MCP for the sub-agents server

• In your MCP configuration, add the following (adjust paths and types as needed):

{
  "mcpServers": {
    "sub-agents": {
      "command": "npx",
      "args": ["-y", "sub-agents-mcp"],
      "env": {
        "AGENTS_DIR": "/absolute/path/to/your/agents-folder",
        "AGENT_TYPE": "cursor"  // or "claude", "gemini", or "codex"
      }
    }
  }
}

Step 4: Start using MCP with your IDE or client

• Ensure the MCP server configuration is loaded by your MCP client.
• Restart your IDE if necessary.
• Use a command like: "Use the code-reviewer agent to review this file" through Cursor/Claude/Gemini/Codex backends.

Notes:

• Use absolute paths for AGENTS_DIR. Relative paths or ~ expansion may fail.
• If you change AGENTS_DIR or AGENT_TYPE, restart your IDE or MCP client to pick up changes.

Tips and common issues:

• Ensure AGENTS_DIR points to a directory containing agent markdown files where each file name becomes the agent name (e.g., code-reviewer.md → code-reviewer).
• AGENT_TYPE tailors integration with the chosen backend (cursor, claude, gemini, codex). Set it to the backend you primarily use.
• Use absolute paths for AGENTS_DIR to avoid path resolution issues across environments.
• If agents fail to initialize, check that the target agent markdown files are valid and lack syntax errors in their Task/Done When sections.
• When upgrading the sub-agents-mcp package, re-check your MCP config for any breaking changes or required env var adjustments.
• For permissions, ensure the MCP process has permission to execute the underlying CLI tool you’ve chosen (cursor-agent, claude, gemini, codex).
• Agent definitions should be self-contained and use the recommended structure: Agent Name, Task, Done When, and optional Out of Scope or Additional sections.
• Restart the MCP client after editing agents or changing environment variables to ensure changes are picked up.