# sub-agents-mcp

Runs your subagents, each described in a Markdown file, through a coding CLI of your choice and sends the result back into the same chat. Useful when reviews, tests and bug hunts should go to separate agents.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed · ★ 98
- Author: shinpr
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/shinpr/sub-agents-mcp
- Updated: 2026-10-22
- HTML: https://affpapa.org/en/nevibecode/mcp/sub-agents-mcp

## What it does

An agent lives as a Markdown file in the folder you point `AGENTS_DIR` at. The file name is the agent name, so `code-reviewer.md` becomes `code-reviewer`. Inside you write the job and the finish criteria. Then you ask your assistant to call that agent, the server executes it on the backend set in `AGENT_TYPE`, and the output lands in the current conversation.

\`AGENT_TYPE` picks the backend: `codex`, `claude`, `cursor`, `command-code`, `glm`, `kimi`, `grok`, `antigravity`, `gemini`, `opencode`, `mcode`, `pi`. That CLI has to be installed and logged in before the server starts. GLM and Kimi also need `CLI_API_KEY` in the environment; the rest rely on their own sign-in. `AGENT_PERMISSION` takes `read-only`, `safe-edit` (the default) or `yolo`. How tightly a level is enforced depends on the backend, so don't treat it as a security boundary.

You need Node.js 22 or newer and an MCP client. If an agent says an action was blocked, loosen the mode. `AGENT_MODEL` pins one model across every agent. With `SESSION_ENABLED` turned on, memory carries between calls, and the assistant has to pass the returned `session_id` to the next request. The agent set is shared across clients while backend and model settings stay in one place.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `AGENTS_DIR`, `AGENT_TYPE`, `AGENT_PERMISSION`, `AGENT_MODEL`, `AGENT_EFFORT`, `CURSOR_API_KEY`, `CLI_API_KEY`, `EXECUTION_TIMEOUT_MS`, `SESSION_ENABLED`, `SESSION_DIR` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env AGENTS_DIR=<AGENTS_DIR> --env AGENT_TYPE=<AGENT_TYPE> --env AGENT_PERMISSION=<AGENT_PERMISSION> --env AGENT_MODEL=<AGENT_MODEL> --env AGENT_EFFORT=<AGENT_EFFORT> --transport stdio sub-agents-mcp -- npx -y sub-agents-mcp
```
Replace <…> with your own values. 7 more environment variables are in the server README

### Codex

**Platform CLI**
```bash
codex mcp add sub-agents-mcp --env AGENTS_DIR=<AGENTS_DIR> --env AGENT_TYPE=<AGENT_TYPE> --env AGENT_PERMISSION=<AGENT_PERMISSION> --env AGENT_MODEL=<AGENT_MODEL> --env AGENT_EFFORT=<AGENT_EFFORT> -- npx -y sub-agents-mcp
```
Replace <…> with your own values. 7 more environment variables are in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "sub-agents-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "sub-agents-mcp"
            ],
            "env": {
                "AGENTS_DIR": "<AGENTS_DIR>",
                "AGENT_TYPE": "<AGENT_TYPE>",
                "AGENT_PERMISSION": "<AGENT_PERMISSION>",
                "AGENT_MODEL": "<AGENT_MODEL>",
                "AGENT_EFFORT": "<AGENT_EFFORT>"
            }
        }
    }
}
```
Replace <…> with your own values. 7 more environment variables are in the server README

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "sub-agents-mcp": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "sub-agents-mcp"
            ],
            "env": {
                "AGENTS_DIR": "<AGENTS_DIR>",
                "AGENT_TYPE": "<AGENT_TYPE>",
                "AGENT_PERMISSION": "<AGENT_PERMISSION>",
                "AGENT_MODEL": "<AGENT_MODEL>",
                "AGENT_EFFORT": "<AGENT_EFFORT>"
            }
        }
    }
}
```
Replace <…> with your own values. 7 more environment variables are in the server README

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e AGENTS_DIR=<AGENTS_DIR> -e AGENT_TYPE=<AGENT_TYPE> -e AGENT_PERMISSION=<AGENT_PERMISSION> -e AGENT_MODEL=<AGENT_MODEL> -e AGENT_EFFORT=<AGENT_EFFORT> sub-agents-mcp npx -y sub-agents-mcp
```
Replace <…> with your own values. 7 more environment variables are in the server README

## When to use it
- route a code review to a dedicated agent with clear criteria
- add tests for a module with a separate subagent
- trace why checkout requests keep failing
- document public API changes
- reuse one set of agents across several editors

## Example prompts
- Use the `code-reviewer` agent to look over the authentication changes
- Have the `bug-investigator` agent find out why checkout requests fail

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md