sub-agents-mcp — MCP server for Claude Code: Markdown-defined
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.
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-mcpWhat sub-agents-mcp 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.
What it helps with
- 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 for the agent
- Use the
code-revieweragent to look over the authentication changes - Have the
bug-investigatoragent find out why checkout requests fail
How to install sub-agents-mcp
Platform CLI
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-mcpReplace <…> with your own values. 7 more environment variables are in the server README
Platform CLI
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-mcpReplace <…> with your own values. 7 more environment variables are in the server README
Config file
{
"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
Config file
{
"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
Platform CLI
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-mcpReplace <…> with your own values. 7 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about sub-agents-mcp
How do I install sub-agents-mcp in Claude Code?
Run `claude mcp add sub-agents-mcp -e AGENTS_DIR=<AGENTS_DIR> -e AGENT_TYPE=<AGENT_TYPE> -e CURSOR_API_KEY=<CURSOR_API_KEY> -e CLI_API_KEY=<CLI_API_KEY> -- npx -y sub-agents-mcp with your own values. The fuller variant is 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`. Restart or reconnect the client after saving.
What does sub-agents-mcp do?
It lets any MCP-compatible client call subagents defined in Markdown files. The server executes the chosen agent through a coding CLI and hands the answer back to the ongoing chat.
What is required for the server to start?
Node.js 22 or later, an MCP client, and the backend CLI installed and signed in. AGENTS_DIR must be an absolute path to a folder holding at least one .md or .txt file.
