Sub Agents
Define task-specific AI sub-agents in Markdown for any MCP-compatible tool.
What is Sub Agents?
Sub Agents is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to define task-specific ai sub-agents in markdown for any mcp-compatible tool.
Define task-specific AI sub-agents in Markdown for any MCP-compatible tool.
This server falls under the Coding Agents category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- run_agent
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx sub-agentsConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Sub Agents
sub-agents-mcp is a TypeScript MCP server that lets you define specialized AI sub-agents as Markdown files and invoke them from any MCP-compatible tool. Each agent is described in a structured Markdown file specifying its purpose, task steps, and completion criteria, and the server executes them via your choice of AI backend — Cursor, Claude Code, OpenAI Codex, or Gemini CLI. This enables complex workflows to be broken into focused, composable sub-tasks with controllable permission levels, timeouts, and optional session continuity across runs.
Prerequisites
- Node.js 18 or higher installed
- At least one supported AI CLI installed: Claude Code (`npm install -g @anthropic-ai/claude-code`), Cursor, OpenAI Codex, or Gemini CLI
- An MCP-compatible client such as Claude Desktop or Cursor
- A directory with agent Markdown files (absolute path required)
Create your agents directory
Create a directory to store your agent definition Markdown files. The path must be absolute — relative paths including `~/` are not supported.
mkdir -p /Users/yourname/agentsWrite an agent definition file
Each agent is a Markdown file with a standardized structure: a name heading, one-line purpose, a Task section with bullet steps, and a Done When section with completion criteria.
# code-reviewer
Review code for bugs, style issues, and security vulnerabilities.
## Task
- Read the specified file or function
- Check for common bugs and edge cases
- Check for security vulnerabilities
- Suggest improvements with explanations
## Done When
- All issues listed with line numbers
- Severity labels applied (critical/warning/info)Add sub-agents-mcp to your MCP client configuration
Configure your MCP client to run sub-agents-mcp via npx. Set AGENTS_DIR to the absolute path of your agents folder and AGENT_TYPE to your preferred execution backend.
{
"mcpServers": {
"sub-agents": {
"command": "npx",
"args": ["-y", "sub-agents-mcp"],
"env": {
"AGENTS_DIR": "/Users/yourname/agents",
"AGENT_TYPE": "claude"
}
}
}
}Configure optional settings
Optionally configure permission levels, execution timeouts, and session persistence. AGENT_PERMISSION controls sandbox access; SESSION_ENABLED enables context continuity between agent runs.
{
"mcpServers": {
"sub-agents": {
"command": "npx",
"args": ["-y", "sub-agents-mcp"],
"env": {
"AGENTS_DIR": "/Users/yourname/agents",
"AGENT_TYPE": "claude",
"AGENT_PERMISSION": "safe-edit",
"EXECUTION_TIMEOUT_MS": "300000",
"SESSION_ENABLED": "false"
}
}
}
}Invoke an agent from your AI assistant
Ask your AI assistant to run a named agent. The server loads the corresponding Markdown file from AGENTS_DIR and executes it via the configured backend.
Sub Agents Examples
Client configuration
Claude Desktop configuration using Claude Code as the execution backend with safe-edit permissions.
{
"mcpServers": {
"sub-agents": {
"command": "npx",
"args": ["-y", "sub-agents-mcp"],
"env": {
"AGENTS_DIR": "/Users/yourname/agents",
"AGENT_TYPE": "claude",
"AGENT_PERMISSION": "safe-edit",
"EXECUTION_TIMEOUT_MS": "300000"
}
}
}
}Prompts to try
Delegate specialized tasks to named sub-agents defined in your agents directory.
- "Use the code-reviewer agent to check my UserService class"
- "Run the test-writer agent on src/utils.ts"
- "Have the documentation agent generate JSDoc for all exported functions in this file"
- "Use the refactor agent to simplify the database connection logic"
- "List all available sub-agents I have configured"Troubleshooting Sub Agents
Agent not found or fails to load
Verify AGENTS_DIR is set to an absolute path (e.g. `/Users/yourname/agents`, not `~/agents`). The agent file name must match exactly what you pass to the tool (e.g. a call for `code-reviewer` requires `code-reviewer.md` in AGENTS_DIR).
Agent execution times out
The default timeout is 5 minutes (300000ms) with a maximum of 10 minutes (600000ms). For long-running tasks, increase `EXECUTION_TIMEOUT_MS` in the configuration. Also consider breaking complex agents into smaller, more focused tasks.
Gemini backend requires an API key
When AGENT_TYPE is set to `gemini`, you must also provide `GEMINI_API_KEY` in the env block. Get your key from Google AI Studio and add it: `"GEMINI_API_KEY": "your-api-key-here"`.
Frequently Asked Questions about Sub Agents
What is Sub Agents?
Sub Agents is a Model Context Protocol (MCP) server that define task-specific ai sub-agents in markdown for any mcp-compatible tool. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Sub Agents?
Follow the installation instructions on the Sub Agents GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with Sub Agents?
Sub Agents works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Sub Agents free to use?
Yes, Sub Agents is open source and available under the MIT license. You can use it freely in both personal and commercial projects.
Sub Agents Alternatives — Similar Coding Agents Servers
Looking for alternatives to Sub Agents? Here are other popular coding agents servers you can use with Claude, Cursor, and VS Code.
Dify
★ 142.2kProduction-ready platform for agentic workflow development.
Ruflo
★ 54.0k🌊 The leading agent orchestration platform for Claude. Deploy intelligent multi-agent swarms, coordinate autonomous workflows, and build conversational AI systems. Features enterprise-grade architecture, self-learning swarm intelligence, RAG integrat
Goose
★ 45.7kan open source, extensible AI agent that goes beyond code suggestions - install, execute, edit, and test with any LLM
Antigravity Awesome Skills
★ 38.3kInstallable GitHub library of 1,400+ agentic skills for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and more. Includes installer CLI, bundles, workflows, and official/community skill collections.
AgentScope
★ 25.5kBuild and run agents you can see, understand and trust.
Serena
★ 24.5kA coding agent toolkit that provides IDE-like semantic code retrieval and editing tools, enabling LLMs to efficiently navigate and modify codebases using symbol-level operations instead of basic file reading and string replacements.
Browse More Coding Agents MCP Servers
Explore all coding agents servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up Sub Agents in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use Sub Agents?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.