{"id":30718183,"url":"https://github.com/shinpr/sub-agents-mcp","last_synced_at":"2026-02-04T23:07:11.190Z","repository":{"id":310073849,"uuid":"1038575316","full_name":"shinpr/sub-agents-mcp","owner":"shinpr","description":"MCP server that enables AI CLI tools to invoke specialized agents","archived":false,"fork":false,"pushed_at":"2025-08-31T10:34:02.000Z","size":289,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-31T10:53:47.726Z","etag":null,"topics":["claude-ai","claude-code","cursor","cursor-ai","mcp","mcp-server","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shinpr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-15T13:07:13.000Z","updated_at":"2025-08-31T10:34:02.000Z","dependencies_parsed_at":"2025-08-15T16:20:44.840Z","dependency_job_id":"b1369c42-6bd9-4df5-956e-0e568ddaebd5","html_url":"https://github.com/shinpr/sub-agents-mcp","commit_stats":null,"previous_names":["shinpr/sub-agents-mcp"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/shinpr/sub-agents-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shinpr%2Fsub-agents-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shinpr%2Fsub-agents-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shinpr%2Fsub-agents-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shinpr%2Fsub-agents-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shinpr","download_url":"https://codeload.github.com/shinpr/sub-agents-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shinpr%2Fsub-agents-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273418404,"owners_count":25102062,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-03T02:00:09.631Z","response_time":76,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-ai","claude-code","cursor","cursor-ai","mcp","mcp-server","typescript"],"created_at":"2025-09-03T09:10:42.500Z","updated_at":"2026-02-04T23:07:11.183Z","avatar_url":"https://github.com/shinpr.png","language":"TypeScript","funding_links":[],"categories":["MCP Servers Directory"],"sub_categories":["Quick Submission"],"readme":"# Sub-Agents MCP Server\n\n[![npm version](https://img.shields.io/npm/v/sub-agents-mcp.svg)](https://www.npmjs.com/package/sub-agents-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nBring Claude Code–style sub-agents to any MCP-compatible tool.\n\nThis 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.\n\n## Why?\n\nClaude 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.\n\n**Concrete benefits:**\n- Define reusable agents once, use them across multiple tools\n- Share agent definitions within teams regardless of IDE choice\n- Leverage Cursor CLI, Claude Code, Gemini CLI, or Codex capabilities from any MCP client\n\n→ [Read the full story](https://dev.to/shinpr/bringing-claude-codes-sub-agents-to-any-mcp-compatible-tool-1hb9)\n\n## Alternative: Agent Skills\n\n[sub-agents-skills](https://github.com/shinpr/sub-agents-skills) offers a lightweight alternative.\n\n| | sub-agents-mcp | sub-agents-skills |\n|---|---|---|\n| **Setup** | MCP configuration required | Copy skill files to your environment |\n| **Features** | Session management, error handling | Minimal |\n| **Stability** | More robust | Lightweight |\n\nChoose **sub-agents-mcp** for production use with reliability features. Choose **sub-agents-skills** for quick setup in Skill-compatible environments.\n\n## Table of Contents\n\n- [Prerequisites](#prerequisites)\n- [Quick Start](#quick-start)\n- [Usage Examples](#usage-examples)\n- [Writing Effective Agents](#writing-effective-agents)\n- [Agent Examples](#agent-examples)\n- [Configuration Reference](#configuration-reference)\n- [Session Management](#session-management)\n- [Troubleshooting](#troubleshooting)\n- [Design Philosophy](#design-philosophy)\n- [How It Works](#how-it-works)\n\n## Prerequisites\n\n- Node.js 20 or higher\n- One of these execution engines (they actually run the sub-agents):\n  - `cursor-agent` CLI (from Cursor)\n  - `claude` CLI (from Claude Code)\n  - `gemini` CLI (from Gemini CLI)\n  - `codex` CLI (from Codex)\n- An MCP-compatible tool (Cursor IDE, Claude Desktop, Windsurf, etc.)\n\n## Quick Start\n\n### 1. Create Your First Agent\n\nCreate a folder for your agents and add `code-reviewer.md`:\n\n```markdown\n# Code Reviewer\n\nReview code for quality and maintainability issues.\n\n## Task\n- Find bugs and potential issues\n- Suggest improvements\n- Check code style consistency\n\n## Done When\n- All target files reviewed\n- Issues listed with explanations\n```\n\nSee [Writing Effective Agents](#writing-effective-agents) for more on agent design.\n\n### 2. Install Your Execution Engine\n\nPick one based on which tool you use:\n\n**For Cursor users:**\n```bash\n# Install Cursor CLI (includes cursor-agent)\ncurl https://cursor.com/install -fsS | bash\n\n# Authenticate (required before first use)\ncursor-agent login\n```\n\n**For Claude Code users:**\n```bash\n# Option 1: Native install (recommended)\ncurl -fsSL https://claude.ai/install.sh | bash\n\n# Option 2: NPM (requires Node.js 18+)\nnpm install -g @anthropic-ai/claude-code\n```\n\nNote: Claude Code installs the `claude` CLI command.\n\n**For Gemini CLI users:**\n```bash\n# Install Gemini CLI\nnpm install -g @google/gemini-cli\n\n# Authenticate via browser (required before first use)\ngemini\n```\n\nNote: Gemini CLI uses OAuth authentication. Run `gemini` once to authenticate via browser.\n\n**For Codex users:**\n```bash\n# Install Codex\nnpm install -g @openai/codex\n```\n\n### 3. Configure MCP\n\nAdd this to your MCP configuration file:\n\n**Cursor:** `~/.cursor/mcp.json`\n**Claude Desktop:** `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)\n\n```json\n{\n  \"mcpServers\": {\n    \"sub-agents\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"sub-agents-mcp\"],\n      \"env\": {\n        \"AGENTS_DIR\": \"/absolute/path/to/your/agents-folder\",\n        \"AGENT_TYPE\": \"cursor\"  // or \"claude\", \"gemini\", or \"codex\"\n      }\n    }\n  }\n}\n```\n\n**Important:** Use absolute paths only.\n- ✅ `/Users/john/Documents/my-agents` (Mac/Linux)\n- ✅ `C:\\\\Users\\\\john\\\\Documents\\\\my-agents` (Windows)\n- ❌ `./agents` or `~/agents` won't work\n\nRestart your IDE and you're ready to go.\n\n### 4. Fix \"Permission Denied\" Errors When Running Shell Commands\n\nSub-agents may fail to execute shell commands with permission errors. This happens because sub-agents can't respond to interactive permission prompts.\n\n**Recommended approach:**\n\n1. Run your CLI tool directly with the task you want sub-agents to handle:\n   ```bash\n   # For Cursor users\n   cursor-agent\n\n   # For Claude Code users\n   claude\n\n   # For Gemini CLI users\n   gemini\n\n   # For Codex CLI users\n   codex\n   ```\n\n2. When prompted to allow commands (e.g., \"Add Shell(cd), Shell(make) to allowlist?\"), approve them\n\n3. This automatically updates your configuration file, and those commands will now work when invoked via MCP sub-agents\n\n**Manual configuration (alternative):**\n\nIf you prefer to configure permissions manually, edit:\n- **Cursor**: `\u003cproject\u003e/.cursor/cli.json` or `~/.cursor/cli-config.json`\n- **Claude Code**: `.claude/settings.json` or `.claude/settings.local.json`\n\n```json\n{\n  \"permissions\": {\n    \"allow\": [\n      \"Shell(cd)\",\n      \"Shell(make)\",\n      \"Shell(git)\"\n    ]\n  }\n}\n```\n\nNote: Agents often run commands as one-liners like `cd /path \u0026\u0026 make build`, so you need to allow all parts of the command.\n\n## Usage Examples\n\nJust tell your AI to use an agent:\n\n```\n\"Use the code-reviewer agent to check my UserService class\"\n```\n\n```\n\"Use the test-writer agent to create unit tests for the auth module\"\n```\n\n```\n\"Use the doc-writer agent to add JSDoc comments to all public methods\"\n```\n\nYour AI automatically invokes the specialized agent and returns results.\n\n**Tip:** Always include *what you want done* in your request—not just which agent to use. For example:\n\n- ✅ \"Use the code-reviewer agent **to check my UserService class**\"\n- ❌ \"Use the code-reviewer agent\" (too vague—the agent won't know what to review)\n\nThe more specific your task, the better the results.\n\n## Writing Effective Agents\n\n### The Single Responsibility Principle\n\nEach agent should do **one thing well**. Avoid \"swiss army knife\" agents.\n\n| ✅ Good | ❌ Bad |\n|---------|--------|\n| Reviews code for security issues | Reviews code, writes tests, and refactors |\n| Writes unit tests for a module | Writes tests and fixes bugs it finds |\n\n### Essential Structure\n\n```markdown\n# Agent Name\n\nOne-sentence purpose.\n\n## Task\n- Action 1\n- Action 2\n\n## Done When\n- Criterion 1\n- Criterion 2\n```\n\n### Keep Agents Self-Contained\n\nAgents run in isolation with fresh context. Avoid:\n\n- References to other agents (\"then use X agent...\")\n- Assumptions about prior context (\"continuing from before...\")\n- Scope creep beyond the stated purpose\n\n### Advanced Patterns\n\nFor complex agents, consider adding:\n\n- **Scope boundaries**: Explicitly state what's *out of scope*\n- **Prohibited actions**: List common mistakes the agent should avoid\n- **Output format**: Define structured output when needed\n\n## Agent Examples\n\nEach `.md` or `.txt` file in your agents folder becomes an agent. The filename becomes the agent name (e.g., `bug-investigator.md` → \"bug-investigator\").\n\n**`bug-investigator.md`**\n```markdown\n# Bug Investigator\n\nInvestigate bug reports and identify root causes.\n\n## Task\n- Collect evidence from error logs, code, and git history\n- Generate multiple hypotheses for the cause\n- Trace each hypothesis to its root cause\n- Report findings with supporting evidence\n\n## Out of Scope\n- Fixing the bug (investigation only)\n- Making assumptions without evidence\n\n## Done When\n- At least 2 hypotheses documented with evidence\n- Most likely cause identified with confidence level\n- Affected code locations listed\n```\n\nFor more advanced patterns (completion checklists, prohibited actions, structured output), see [claude-code-workflows/agents](https://github.com/shinpr/claude-code-workflows/tree/main/agents). These are written for Claude Code, but the design patterns apply to any execution engine.\n\n## Configuration Reference\n\n### Required Environment Variables\n\n**`AGENTS_DIR`**\nPath to your agents folder. Must be absolute.\n\n**`AGENT_TYPE`**\nWhich execution engine to use:\n- `\"cursor\"` - uses `cursor-agent` CLI\n- `\"claude\"` - uses `claude` CLI\n- `\"gemini\"` - uses `gemini` CLI\n- `\"codex\"` - uses `codex` CLI (OpenAI Codex)\n\n### Optional Settings\n\n**`EXECUTION_TIMEOUT_MS`**\nHow long agents can run before timing out (default: 5 minutes, max: 10 minutes)\n\n**`AGENTS_SETTINGS_PATH`**\nPath to custom CLI settings directory for sub-agents.\n\nEach 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.\n\nSupported CLI types: `claude`, `cursor`, `codex`\n\nNote: Gemini CLI does not support custom settings paths, so this option has no effect when `AGENT_TYPE` is `gemini`.\n\nExample with custom settings:\n```json\n{\n  \"mcpServers\": {\n    \"sub-agents\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"sub-agents-mcp\"],\n      \"env\": {\n        \"AGENTS_DIR\": \"/absolute/path/to/agents\",\n        \"AGENT_TYPE\": \"cursor\",\n        \"EXECUTION_TIMEOUT_MS\": \"600000\",\n        \"AGENTS_SETTINGS_PATH\": \"/absolute/path/to/custom-cli-settings\"\n      }\n    }\n  }\n}\n```\n\n### Security Note\n\nAgents have access to your project directory. Only use agent definitions from trusted sources.\n\n## Session Management\n\nSession 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.\n\n### Why Sessions Matter\n\nBy default, each sub-agent execution starts with no context. With sessions enabled:\n- Agents can reference their earlier work\n- You get execution history for debugging\n- Related tasks share context\n\n### Enabling Sessions\n\nAdd these environment variables to your MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"sub-agents\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"sub-agents-mcp\"],\n      \"env\": {\n        \"AGENTS_DIR\": \"/absolute/path/to/agents\",\n        \"AGENT_TYPE\": \"cursor\",\n        \"SESSION_ENABLED\": \"true\",\n        \"SESSION_DIR\": \"/absolute/path/to/session-storage\",\n        \"SESSION_RETENTION_DAYS\": \"1\"\n      }\n    }\n  }\n}\n```\n\n**Configuration options:**\n\n- `SESSION_ENABLED` - Set to `\"true\"` to enable session management (default: `false`)\n- `SESSION_DIR` - Where to store session files (default: `.mcp-sessions` in the current working directory)\n- `SESSION_RETENTION_DAYS` - How long to keep session files based on last modification time in days (default: 1)\n\n**Security consideration:** Session files contain execution history and may include sensitive information. Use absolute paths for `SESSION_DIR`.\n\n### When to Use Sessions\n\nSessions work well for:\n- **Iterative development**: \"Based on your earlier findings, now fix the issues\"\n- **Multi-step workflows**: Breaking complex tasks into smaller sub-agent calls\n- **Debugging**: Reviewing exactly what was executed and what results were returned\n\nNote that sessions require additional storage and processing overhead.\n\n### How Session Continuity Works\n\nWhen sessions are enabled, the MCP response includes a `session_id` field. To continue the same session, pass this ID back in the next request.\n\n**Important:** Your AI assistant must explicitly include the session_id in subsequent requests. While some assistants may do this automatically, it's not guaranteed. For reliable session continuity, add explicit instructions to your prompts or project rules.\n\n**Example prompt instruction:**\n```markdown\nWhen using sub-agents with sessions enabled, always include the session_id\nfrom the previous response in your next request to maintain context.\n```\n\n**Example project rule (e.g., `AGENTS.md`):**\n```markdown\n# Sub-Agent Session Guidelines\n\nWhen calling the same sub-agent multiple times:\n1. Extract the session_id from the MCP response\n2. Pass it as a parameter in subsequent calls\n3. This preserves context between executions\n```\n\n## Troubleshooting\n\n### Timeout errors or authentication failures\n\n**If using Cursor CLI:**\nRun `cursor-agent login` to authenticate. Sessions can expire, so just run this command again if you see auth errors.\n\nVerify installation:\n```bash\nwhich cursor-agent\n```\n\n**If using Claude Code:**\nMake sure the CLI is properly installed and accessible.\n\n### Agent not found\n\nCheck that:\n- `AGENTS_DIR` points to the correct directory (use absolute path)\n- Your agent file has `.md` or `.txt` extension\n- The filename uses hyphens or underscores (no spaces)\n\n### Other execution errors\n\n1. Verify `AGENT_TYPE` is set correctly (`cursor`, `claude`, `gemini`, or `codex`)\n2. Ensure your chosen CLI tool is installed and accessible\n3. Double-check that all environment variables are set in the MCP config\n\n### Recursive sub-agent calls (infinite loop)\n\nIf sub-agents keep spawning more sub-agents, there are typically two causes:\n\n**1. MCP configuration inheritance**\n\nCreate a separate settings directory without the sub-agents MCP configuration and specify it via `AGENTS_SETTINGS_PATH`. This prevents sub-agents from having access to this MCP server.\n\n**2. AGENTS.md instruction inheritance (Codex)**\n\nCodex concatenates AGENTS.md from CODEX_HOME and project root. If your project AGENTS.md has delegation instructions, sub-agents inherit them too.\n\nSolution: Don't place AGENTS.md at the project root. Use separate directories:\n```\n/your-project\n├── .codex-main/AGENTS.md      # Main agent instructions\n├── .codex-sub/AGENTS.md       # Sub-agent instructions (no delegation)\n└── (no AGENTS.md at root)\n```\n\n- Run main Codex with `CODEX_HOME=/your-project/.codex-main`\n- Set `AGENTS_SETTINGS_PATH=/your-project/.codex-sub` in sub-agents-mcp config\n\n## Design Philosophy\n\n### Why Independent Contexts Matter\n\nEvery sub-agent starts with a fresh context. This adds some startup overhead for each call, but it ensures that every task runs independently and without leftover state from previous runs.\n\n**Context Isolation**\n- Each agent only receives the information relevant to its task\n- No context leakage between runs\n- The main agent stays focused and lightweight\n\n**Accuracy and Reliability**\n- Sub-agents can specialize in a single goal without interference\n- Less risk of confusion from unrelated context\n- More consistent results in complex, multi-step workflows\n\n**Scalability**\n- Large tasks can be safely split into smaller sub-tasks\n- Each sub-agent operates within its own token limit\n- The main agent coordinates without hitting global context limits\n\nThe startup overhead is an intentional trade-off: the system favors clarity and accuracy over raw execution speed.\n\n## How It Works\n\nThis MCP server acts as a bridge between your AI tool and a supported execution engine (Cursor CLI, Claude Code, Gemini CLI, or Codex).\n\n**The flow:**\n\n1. You configure the MCP server in your client (Cursor, Claude Desktop, etc.)\n2. The client automatically launches `sub-agents-mcp` as a background process when it starts\n3. When your main AI assistant needs a sub-agent, it makes an MCP tool call\n4. The MCP server reads the agent definition (markdown file) and invokes the selected CLI (`cursor-agent`, `claude`, `gemini`, or `codex`)\n5. The execution engine runs the agent and streams results back through the MCP server\n6. Your main assistant receives the results and continues working\n\nThis architecture lets any MCP-compatible tool benefit from specialized sub-agents, even if it doesn't have native support.\n\n## License\n\nMIT\n\n---\n\n*AI-to-AI collaboration through Model Context Protocol*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshinpr%2Fsub-agents-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshinpr%2Fsub-agents-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshinpr%2Fsub-agents-mcp/lists"}