# sub-agents-mcp [Health: Active]

**Category:** 🤖 Coding Agents  
**Repository:** https://github.com/shinpr/sub-agents-mcp  
**GitHub Stars:** 98  
**npm Downloads (last month):** 1261  
**Views:** 8  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/sub-agents-mcp

## Description
MCP server for delegating tasks to specialized AI assistants in Cursor and other tools

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "sub-agents-mcp": {
    "command": "npx",
    "args": ["-y","sub-agents-mcp"],
    "env": {
      "AGENTS_DIR": "",
      "AGENT_TYPE": "",
      "CLI_API_KEY": "",
      "AGENT_MODEL": "",
      "AGENT_PERMISSION": "",
      "SESSION_ENABLED": ""
    }
  }
}
```

**Requires environment variables:** `AGENTS_DIR`, `AGENT_TYPE`, `CLI_API_KEY`, `AGENT_MODEL`, `AGENT_PERMISSION`, `SESSION_ENABLED` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What sub-agents-mcp does

sub-agents-mcp exposes reusable coding agents through the Model Context Protocol. Each agent is a Markdown file containing instructions, task guidance, and completion criteria. The filename becomes the agent name, so `code-reviewer.md` can be invoked as `code-reviewer`.

Agents can handle focused development work such as reviewing changes, adding tests, investigating failures, or writing documentation. An MCP client sends the requested agent and task to the server, which runs the agent through a selected coding CLI and returns the result to the same conversation.

The server is useful when a team wants one set of agent definitions to work across multiple MCP clients while keeping backend and model choices centralized.

## How it works

Create an agents directory and add one or more `.md` or `.txt` agent files. Configure the MCP client to launch the package with `npx`, supplying the absolute agents directory and the backend type. After the client reconnects, an assistant can invoke an agent by name and describe the work it should perform.

The selected backend CLI must already be installed and authenticated. Available backend types include Codex, Claude Code, Cursor CLI, Command Code, GLM, Kimi, Grok Build, Google Antigravity, Gemini CLI, OpenCode, MiniMax Code, and Pi. GLM and Kimi additionally require `CLI_API_KEY`; other backends use their existing CLI authentication.

Set `AGENT_MODEL` to apply one model to every agent, or leave it unset to use the backend default. `AGENT_PERMISSION` provides read-only, safe-edit, and unrestricted execution modes. These modes depend on backend behavior and should be treated as guidance rather than a security boundary.

## Setup and configuration

The runtime requires Node.js 22 or later, an MCP-compatible client, and an installed, signed-in supported coding CLI. A minimal MCP configuration sets `AGENTS_DIR` to the absolute path of the agent directory and `AGENT_TYPE` to the chosen backend, such as `codex`.

After changing the MCP configuration, restart or reconnect the client. If the server does not start, run the selected CLI directly to verify installation and authentication, check that the agent path is absolute, and confirm that the directory contains at least one supported text file.

Set `SESSION_ENABLED` to `true` to preserve work between calls. Continuing a session requires passing the returned `session_id` into the next call.

## Tools and capabilities

- Runs named Markdown-defined coding agents from an MCP client.
- Delegates reviews, test creation, investigations, and documentation tasks.
- Shares agent definitions across MCP clients.
- Applies shared model and permission settings to agents.
- Supports continued work through returned session identifiers.
- Connects agent execution to multiple coding CLI backends.

## Limitations and notes

Agent permission levels are not guaranteed security controls; enforcement varies by backend. The selected CLI must be configured before the MCP server starts. Session continuation also depends on the calling assistant reusing the returned session identifier.

_Full upstream README: https://allmcps.com/mcp/sub-agents-mcp/readme_