Sub-Agents MCP Server

Bring Claude Code–style sub-agents to any MCP-compatible tool.

This MCP server lets you define task-specific AI agents (like "test-writer" or "code-reviewer") in markdown files, and execute them via Cursor CLI, Claude Code, Gemini CLI, or Codex backends.

Why?

Claude Code offers powerful sub-agent workflows—but they're limited to its own environment. This MCP server makes that workflow portable, so any MCP-compatible tool (Cursor, Claude Desktop, Windsurf, etc.) can use the same agents.

Concrete benefits:

• Define reusable agents once, use them across multiple tools
• Share agent definitions within teams regardless of IDE choice
• Leverage Cursor CLI, Claude Code, Gemini CLI, or Codex capabilities from any MCP client

→ Read the full story

Alternative: Agent Skills

sub-agents-skills offers a lightweight alternative.

Choose sub-agents-mcp for production use with reliability features. Choose sub-agents-skills for quick setup in Skill-compatible environments.

Table of Contents

• Prerequisites
• Quick Start
• Usage Examples
• Writing Effective Agents
• Agent Examples
• Configuration Reference
• Session Management
• Troubleshooting
• Design Philosophy
• How It Works

Prerequisites

• Node.js 20 or higher
• One of these execution engines (they actually run the sub-agents):
  • cursor-agent CLI (from Cursor)
  • claude CLI (from Claude Code)
  • gemini CLI (from Gemini CLI)
  • codex CLI (from Codex)
• An MCP-compatible tool (Cursor IDE, Claude Desktop, Windsurf, etc.)

Quick Start

1. Create Your First Agent

Create a folder for your agents and add code-reviewer.md:

# Code Reviewer

Review code for quality and maintainability issues.

## Task
- Find bugs and potential issues
- Suggest improvements
- Check code style consistency

## Done When
- All target files reviewed
- Issues listed with explanations

See Writing Effective Agents for more on agent design.

2. Install Your Execution Engine

Pick one based on which tool you use:

For Cursor users:

# Install Cursor CLI (includes cursor-agent)
curl https://cursor.com/install -fsS | bash

# Authenticate (required before first use)
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

Note: Claude Code installs the claude CLI command.

For Gemini CLI users:

# Install Gemini CLI
npm install -g @google/gemini-cli

# Authenticate via browser (required before first use)
gemini

Note: Gemini CLI uses OAuth authentication. Run gemini once to authenticate via browser.

For Codex users:

# Install Codex
npm install -g @openai/codex

3. Configure MCP

Add this to your MCP configuration file:

Cursor: ~/.cursor/mcp.json Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

{
  "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"
      }
    }
  }
}

Important: Use absolute paths only.

• ✅ /Users/john/Documents/my-agents (Mac/Linux)
• ✅ C:\Users\john\Documents\my-agents (Windows)
• ❌ ./agents or ~/agents won't work

Restart your IDE and you're ready to go.

4. Fix "Permission Denied" Errors When Running Shell Commands

Sub-agents may fail to execute shell commands with permission errors. This happens because sub-agents can't respond to interactive permission prompts.

Recommended approach:

1. Run your CLI tool directly with the task you want sub-agents to handle:

   # For Cursor users
   cursor-agent
   
   # For Claude Code users
   claude
   
   # For Gemini CLI users
   gemini
   
   # For Codex CLI users
   codex
   

2. When prompted to allow commands (e.g., "Add Shell(cd), Shell(make) to allowlist?"), approve them

3. This automatically updates your configuration file, and those commands will now work when invoked via MCP sub-agents

Manual configuration (alternative):

If you prefer to configure permissions manually, edit:

• Cursor: <project>/.cursor/cli.json or ~/.cursor/cli-config.json
• Claude Code: .claude/settings.json or .claude/settings.local.json

{
  "permissions": {
    "allow": [
      "Shell(cd)",
      "Shell(make)",
      "Shell(git)"
    ]
  }
}

Note: Agents often run commands as one-liners like cd /path && make build, so you need to allow all parts of the command.

Usage Examples

Just tell your AI to use an agent:

"Use the code-reviewer agent to check my UserService class"

"Use the test-writer agent to create unit tests for the auth module"

"Use the doc-writer agent to add JSDoc comments to all public methods"

Your AI automatically invokes the specialized agent and returns results.

Tip: Always include what you want done in your request—not just which agent to use. For example:

• ✅ "Use the code-reviewer agent to check my UserService class"
• ❌ "Use the code-reviewer agent" (too vague—the agent won't know what to review)

The more specific your task, the better the results.

Writing Effective Agents

The Single Responsibility Principle

Each agent should do one thing well. Avoid "swiss army knife" agents.

Essential Structure

# Agent Name

One-sentence purpose.

## Task
- Action 1
- Action 2

## Done When
- Criterion 1
- Criterion 2

Keep Agents Self-Contained

Agents run in isolation with fresh context. Avoid:

• References to other agents ("then use X agent...")
• Assumptions about prior context ("continuing from before...")
• Scope creep beyond the stated purpose

Advanced Patterns

For complex agents, consider adding:

• Scope boundaries: Explicitly state what's out of scope
• Prohibited actions: List common mistakes the agent should avoid
• Output format: Define structured output when needed

Agent Examples

Each .md or .txt file in your agents folder becomes an agent. The filename becomes the agent name (e.g., bug-investigator.md → "bug-investigator").

bug-investigator.md

# Bug Investigator

Investigate bug reports and identify root causes.

## Task
- Collect evidence from error logs, code, and git history
- Generate multiple hypotheses for the cause
- Trace each hypothesis to its root cause
- Report findings with supporting evidence

## Out of Scope
- Fixing the bug (investigation only)
- Making assumptions without evidence

## Done When
- At least 2 hypotheses documented with evidence
- Most likely cause identified with confidence level
- Affected code locations listed

For more advanced patterns (completion checklists, prohibited actions, structured output), see claude-code-workflows/agents. These are written for Claude Code, but the design patterns apply to any execution engine.

Configuration Reference

Required Environment Variables

AGENTS_DIR Path to your agents folder. Must be absolute.

AGENT_TYPE Which execution engine to use:

• "cursor" - uses cursor-agent CLI
• "claude" - uses claude CLI
• "gemini" - uses gemini CLI
• "codex" - uses codex CLI (OpenAI Codex)

Optional Settings

EXECUTION_TIMEOUT_MS How long agents can run before timing out (default: 5 minutes, max: 10 minutes)

AGENTS_SETTINGS_PATH Path to custom CLI settings directory for sub-agents.

Each CLI normally reads settings from project-level directories (.claude/, .cursor/, .codex/) or user-level directories (~/.claude/, ~/.cursor/, ~/.codex/). If you want sub-agents to run with different settings (e.g., different permissions or model), specify a separate settings directory here.

Supported CLI types: claude, cursor, codex

Note: Gemini CLI does not support custom settings paths, so this option has no effect when AGENT_TYPE is gemini.

Example with custom settings:

{
  "mcpServers": {
    "sub-agents": {
      "command": "npx",
      "args": ["-y", "sub-agents-mcp"],
      "env": {
        "AGENTS_DIR": "/absolute/path/to/agents",
        "AGENT_TYPE": "cursor",
        "EXECUTION_TIMEOUT_MS": "600000",
        "AGENTS_SETTINGS_PATH": "/absolute/path/to/custom-cli-settings"
      }
    }
  }
}

Security Note

Agents have access to your project directory. Only use agent definitions from trusted sources.

Session Management

Session management allows sub-agents to remember previous executions, which helps when you want agents to build on earlier work or maintain context across multiple calls.

Why Sessions Matter

By default, each sub-agent

---