Sub-Agents MCP Server

How to use

Define your agents once as markdown files in a dedicated folder, then tell your MCP-enabled client to run those agents on demand. When you want an agent to perform a task, reference it by name, specify the action you want, and let the MCP server route the request to the chosen execution engine. The server handles invoking the appropriate CLI (Cursor, Claude Code, Gemini, or Codex) and streams results back to your assistant.

How to install

Prerequisites: ensure you have Node.js 20 or higher installed on your machine.

Create your first agent by making a folder for agents and adding a file such as code-reviewer.md with your agent definition. For example:

# Code Reviewer

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

Install the execution engine you use to run sub-agents. Pick one based on your toolchain.

# For Cursor users
curl https://cursor.com/install -fsS | bash
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

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

# Authenticate via browser (required before first use)
gemini

# For Codex users
npm install -g @openai/codex

Configure MCP

Create the MCP configuration that launches the sub-agent runner. Use a stdio (local) MCP server configuration so your client starts sub-agents-mcp as a background process.

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

Usage examples

Tell your AI to use a specific agent to perform a task. Example prompts:

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

Agent examples

Each agent is a markdown or text file. The filename becomes the agent name (for example, code-reviewer.md). The file contains a short description of the agent’s role and bullet guidance for its behavior.

# Test Writer
You specialize in writing comprehensive unit tests.
- Cover edge cases
- Follow project testing patterns
- Ensure good coverage

Configuration reference

Environment variables you may configure for the MCP server: AGENTS_DIR (required, absolute path to your agents folder) and AGENT_TYPE (cursor, claude, gemini, or codex). You can also set an optional execution timeout.

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

Session management

You can enable sessions to allow sub-agents to remember prior work and maintain context across calls. Enable by adding SESSION_ENABLED and related session settings to your MCP config. Sessions help with iterative development, multi-step workflows, and debugging by preserving history.

{
  "mcpServers": {
    "sub-agents": {
      "command": "npx",
      "args": ["-y", "sub-agents-mcp"],
      "env": {
        "AGENTS_DIR": "/absolute/path/to/agents",
        "AGENT_TYPE": "cursor",
        "SESSION_ENABLED": "true",
        "SESSION_DIR": "/absolute/path/to/session-storage",
        "SESSION_RETENTION_DAYS": "1"
      }
    }
  }
}

Troubleshooting

If you encounter permission prompts when the sub-agents try to run shell commands, approve those prompts in the CLI you use to start the agent and your configuration will update to allow subsequent commands.

Common issues include ensuring the correct AGENTS_DIR path, using an authorized agent file extension (.md or .txt), and verifying the chosen agent type matches the installed CLI (cursor, claude, gemini, or codex). If commands fail, confirm the environment variables are set in the MCP config.

Design philosophy

Each sub-agent runs in isolation to avoid context leakage and ensure reliability. This design favors clarity and correctness over raw speed, enabling scalable, multi-step workflows where each sub-agent focuses on a single goal.

How it works

The MCP server bridges your AI tool with a supported execution engine. You configure the server in your client, the server launches sub-agents-mcp, and when you request a sub-agent, the server reads the agent file and invokes the corresponding CLI (cursor-agent, claude, gemini, or codex). The engine runs the agent and streams results back to your main assistant.

License

MIT

sub-agents-mcp

MCP server that executes markdown-defined agents using various CLI backends (Cursor, Claude Code, Gemini, Codex)

cursor-agent

CLI tool from Cursor to run sub-agents within the MCP workflow

claude

CLI tool from Claude Code to run sub-agents within the MCP workflow

gemini

CLI tool from Gemini to run sub-agents within the MCP workflow

codex

CLI tool from OpenAI Codex to run sub-agents within the MCP workflow