Sub-Agents

This MCP server lets you define task-specific AI agents in markdown files and execute them through multiple backends like Cursor, Claude Code, Gemini, or Codex. It brings Claude Code–style sub-agent workflows to any MCP-compatible tool, so you can reuse agent definitions across tools and collaborate without being tied to a single environment.

How to use

You configure a sub-agents MCP server in your client, then tell your AI assistant to use a specific agent for a task. Create agent definitions as markdown files in your agents folder, then invoke the corresponding MCP server to run the agent through your chosen backend. You can run agents via Cursor CLI, Claude Code, Gemini CLI, or Codex backends, enabling cross-tool workflows and consistent agent behavior.

How to install

Prerequisites: install Node.js 20 or higher and choose an execution engine to run the sub-agents.

# Prerequisites (example)
node -v
# Ensure Node.js 20+ is installed

Configuration and usage details

Configure MCP to run sub-agents by pointing it at your agents folder and selecting an execution engine. The following example shows the project-level MCP configuration for a Cursor-based setup.

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

Agent design and usage patterns

Create a folder for your agents and add markdown files like code-reviewer.md or test-writer.md. Each file defines a single, focused task following the structure below.

Agent files should be self-contained and describe task goals, steps, and completion criteria in a single responsibility per agent.

Writing Effective Agents

Follow the Single Responsibility Principle: each agent should do one thing well. Use a clear structure with a short name, a task list, and a Done When section. Keep agents self-contained and avoid references to other agents or prior context.

Agent examples

An agent file named code-reviewer.md could look like this:

# 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

Available tools

cursor

Cursor CLI integration to run sub-agent tasks via the Cursor environment.

claude

Claude Code CLI to execute sub-agents through Claude's backend.

gemini

Gemini CLI to run sub-agents using Gemini's backend.

codex

OpenAI Codex CLI to execute sub-agents via Codex backend.