Sub-Agents MCP Server

How to use

You load agents from a folder where each markdown or text file defines an agent, such as a code-reviewer or test-writer. In your MCP client, enable the sub-agents MCP server and point it to your agents directory. When your main AI assistant needs a sub-agent, tell it to use the desired agent, and the MCP server will invoke the corresponding CLI (cursor-agent or claude) and return the results.

How to install

Prerequisites you need before installing the MCP server:

- Node.js 20 or higher

- One of these execution engines to run sub-agents:

- cursor-agent CLI (from Cursor)

- claude CLI (from Claude Code)

Step 1 — Create Your First Agent

# Code Reviewer

You are a specialized AI assistant that reviews code.
Focus on:
- Finding bugs and potential issues
- Suggesting improvements
- Checking code quality

Step 2 — Install Your Execution Engine

Choose the execution engine that matches your MCP client.

For Cursor users:

curl https://cursor.com/install -fsS | bash

Then authenticate:

cursor-agent login

For Claude Code users:

# Option 1: Native install (recommended)
curl -fsSL https://claude.ai/install.sh | bash

# Option 2: NPM (requires Node.js 18+)
npm install -g @anthropic-ai/claude-code

Step 3 — Configure MCP

Add the MCP server configuration to your client so it can launch sub-agents. The following example uses an MCP configuration path for Cursor. Use your actual path for your environment.

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

Step 4 — Start Using Sub-Agents

Restart your MCP client or IDE after applying the configuration. Your agent files are loaded from the folders you specified in AGENTS_DIR, and you can reference them by their file names (for example, code-reviewer.md becomes the code-reviewer agent). When you request an agent, the MCP server runs the appropriate CLI and streams the result back to you.

Additional sections

Configuration Reference Required environment variables shown in the examples include AGENTS_DIR and AGENT_TYPE. You may also enable and configure session management for ongoing context across multiple runs by setting additional environment variables as described in the Session Management section.

Session Management You can enable the MCP server to remember previous executions by turning on sessions. This helps agents build on earlier work and maintain context across calls. To enable, set SESSION_ENABLED to true and provide a session storage location and retention period in your MCP config.

Troubleshooting If you encounter issues, verify AGENTS_DIR paths are absolute, ensure AGENT_TYPE matches your chosen engine, and confirm the required CLI tools are installed and accessible from your environment. Check for permission prompts during shell commands and approve them when they appear.

Design Philosophy Sub-agents operate with isolated contexts to ensure clarity and reliability for each task, while still enabling multi-step workflows through coordinated calls from the main agent.

How It Works A client configures the MCP server to load agents. When the main AI needs a sub-agent, it triggers the MCP server, which reads the agent definition and invokes the chosen CLI (cursor-agent or claude). Results stream back to the main AI, enabling seamless, cross-tool agent workflows.

code-reviewer

A specialized agent that reviews code for bugs, improvements, and quality.

test-writer

An agent focused on writing comprehensive unit tests, covering edge cases and following patterns.

doc-writer

An agent that adds documentation comments and JSDoc-style notes to public APIs.

sql-expert

A database-focused agent that helps optimize queries and design indexes.

security-checker

An agent that checks for security vulnerabilities and related risks.