Sub-Agents MCP Server
An MCP server that runs sub-agents defined in Markdown through Codex, Claude Code, Cursor CLI and other CLIs from any MCP client
- 98 ★ on the repository
- Last commit
Broad access
Why this level
- Launches installed coding CLIs that read and edit project files, and yolo mode removes restrictions
- The AGENT_PERMISSION limits depend on the backend and serve as guidance
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add mcp/sub-agents-mcp-serverDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Launches installed coding CLIs that read and edit project files, and yolo mode removes restrictions
- The AGENT_PERMISSION limits depend on the backend and serve as guidance
This is third-party code. Review the repository files before installing.
What it does
Sub-Agents MCP Server runs reusable agents defined in Markdown. A role (reviewer, test writer, bug investigator, doc writer) is written as `code-reviewer.md` in a folder you choose, and the file name becomes the agent name. The server plugs into an MCP client, and on a request like "use the code-reviewer agent to review the authentication changes" it launches the chosen CLI and returns the result to the same conversation. The backend is set by `AGENT_TYPE`: `codex`, `claude`, `cursor`, `command-code`, `glm`, `kimi`, `grok`, `antigravity`, `gemini`, `opencode`, `mcode` or `pi`. One model serves all agents (`AGENT_MODEL`), and `AGENT_PERMISSION` sets rights: `read-only`, `safe-edit` (default) or `yolo`. With `SESSION_ENABLED` an agent can continue between calls by `session_id`. The server needs Node.js 22 or newer and one installed, signed-in CLI. For GLM and Kimi add `CLI_API_KEY` to the environment.
Who it is for. Developers who want to call a reviewer or test writer from Claude Desktop, Cursor or another MCP client and keep agent definitions in one folder.
Good fit when
- Change review should go to a separate agent with clear instructions instead of the general chat
- The same agents are needed in several MCP clients with backend and model configured in one place
- A long task has to run across several calls with memory, using `SESSION_ENABLED`
- Investigating failed checkouts should go to a read-only agent in `read-only` mode
Not a fit when
- You want the lightest setup: the author has a separate Sub-Agents Skills project with no server
- Each agent must pick its own backend and model: the server shares them across all
- You need a hard security boundary: `AGENT_PERMISSION` depends on the backend and is only guidance
Example request
Use the code-reviewer agent to review the authentication changes on the current branchMCP
- Transport
- stdio
- Authentication
- not required
Environment variables
AGENTS_DIRrequired- Absolute path to the folder with agent files (.md or .txt)
AGENT_TYPErequired- Backend: codex, claude, cursor, gemini, opencode and others
AGENT_PERMISSION- read-only, safe-edit (default) or yolo
CLI_API_KEYsecret- Key for the GLM and Kimi backends
Limitations
- Node.js 22 or newer and one installed, signed-in CLI from the backend list are required, or the server will not start.
- Backend and model are shared by all agents, and per-agent choice is offered by the separate Sub-Agents Skills project.
- By the author's words the `AGENT_PERMISSION` modes are guidance and not a security boundary: strictness depends on the backend. The `yolo` mode removes every restriction.
- GLM and Kimi need `CLI_API_KEY`; other backends use the CLI's own authentication.
How to disable. Remove the `sub-agents` block from the MCP client configuration and restart the client. The folder with agent definitions stays on disk and can be deleted by hand.
FAQ
How do I connect Sub-Agents MCP to Claude Desktop or Cursor?
Add a `sub-agents` server to the MCP config with the command `npx -y sub-agents-mcp` and the variables `AGENTS_DIR` (absolute path to the agents folder) and `AGENT_TYPE` (for example `codex`). Restart the client after saving.
How do I define an agent?
Create a Markdown file such as `code-reviewer.md` with a title and `Task` and `Done When` sections. The file name without extension becomes the agent name, and `.md` and `.txt` files in `AGENTS_DIR` are picked up automatically.
What rights does a sub-agent get?
`AGENT_PERMISSION` sets them: `read-only` for review and investigation, `safe-edit` (default) allows edits without approval and `yolo` removes limits. Strictness depends on the backend.
Which backends are supported?
Codex, Claude Code, Cursor CLI, Command Code, GLM, Kimi, Grok Build, Google Antigravity, Gemini CLI, OpenCode, MiniMax Code and Pi. The chosen CLI must be installed and signed in before the server starts.
Why does an agent not start?
Check that the chosen CLI works on its own in a terminal and is signed in, that `AGENTS_DIR` is an absolute path with at least one `.md` or `.txt` file, and that the client was restarted after the config change.
Discussion
No questions or reviews yet.
Related
MCP serversUseAgent’s MCP server sends tasks to remote agents, collects their results and records the runs in an organization’s ledger.
ReevesAgents runs Claude Code, Codex, Hermes and other CLI agents side by side in tmux; an MCP lets one lead the rest.
MCP Agent Mail
mcp_agent_mail
A mail coordination layer for coding agents: agents have memorable names, inboxes and outboxes, history search and voluntary file reservations
A bridge between local CLI agents: Codex, Cursor or Claude Code delegate work to Antigravity, Grok, Kimi and seven more.
PromptOps keeps Claude Code, Codex and Gemini CLI side by side by project and gives a lead agent MCP to launch helpers
MCP server for a shared agent room: decisions, tasks verified by another agent and a final report, joined by code.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Sub-Agents MCP Server (this card) | no | not required | 98 | |
| pi-subagents | no | 1,449 | a sub-agent plugin for Pi with no bridge to different CLIs | |
| Oh My Subagents | no | 180 | a local service for Codex and Claude sub-agent teams that tracks task state |
README in short
The README walks three steps: create an agent file, add the server to the MCP config, call the agent with a request. It then gives request examples, a backend table with CLI commands, shared model and permission settings, sessions across calls and tips for when the server does not start.