Log inSubmit server
Sub Agents MCP logo

Sub Agents MCP

Delegates reusable Markdown-defined coding agents to a selected coding CLI through MCP-compatible clients.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Sub Agents MCP

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "sub-agents-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "sub-agents-mcp"
      ],
      "env": {
        "AGENTS_DIR": "YOUR_VALUE_HERE",
        "AGENT_TYPE": "YOUR_VALUE_HERE",
        "CLI_API_KEY": "YOUR_VALUE_HERE",
        "AGENT_MODEL": "YOUR_VALUE_HERE",
        "AGENT_PERMISSION": "YOUR_VALUE_HERE",
        "SESSION_ENABLED": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

Install not yet sandbox-tested— we haven't run this command through our automated sandbox yet. Not a red flag; we're working through the catalog.

Overview

sub-agents-mcp lets MCP-compatible clients run reusable coding agents defined in Markdown files, using a configured coding CLI as the backend. It supports tasks such as code review, test writing, investigation, and documentation, and can continue an agent across calls when sessions are enabled. Reach for it when several MCP clients should share the same agent definitions, backend, and model settings. Supported backends include Codex, Claude Code, Cursor CLI, Gemini CLI, OpenCode, and others.

Use cases

  • Delegate code reviews to a reusable reviewer agent
  • Generate unit tests with a dedicated test-writing agent
  • Investigate failed requests through a focused debugging agent
  • Document API changes with a reusable documentation agent
  • Share agent definitions across MCP clients

Key features

  • Markdown-defined reusable agents
  • Multiple coding CLI backends
  • Shared model and permission settings
  • Cross-client agent reuse
  • Optional session continuation
  • Configurable execution permissions

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked Today

Recent health check succeeded.

11/11 checks healthy over the last 45d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 15d ago via OSV.dev · sub-agents-mcp (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars98Stargazers on the source repository.
npm downloads1.3kPackage downloads in the last 30 days.
Last commit6d agoMost recent push to the default branch.
Directory activity8 viewsConfig copies, upvotes, and views on AllMCPs.

How Sub Agents MCP works

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.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Sub Agents MCP

sub-agents-mcp is an MCP server that connects MCP-compatible clients to configured coding CLIs such as Codex, Claude Code, Cursor CLI, and Gemini CLI. Its main tools run reusable Markdown-defined agents for reviews, tests, investigations, and documentation, then return results to the client conversation.

Install it through an MCP client configuration using `npx -y sub-agents-mcp`. Node.js 22 or later is required. Set `AGENTS_DIR` to an absolute directory containing agent files and `AGENT_TYPE` to a supported backend, then restart or reconnect the client.

Create a Markdown file in the configured agents directory and put the agent instructions in it. The filename becomes the agent name, so `code-reviewer.md` is invoked as `code-reviewer`. Include the task description and criteria that define when the work is complete.

sub-agents-mcp supports Codex, Claude Code, Cursor CLI, Command Code, GLM, Kimi, Grok Build, Google Antigravity, Gemini CLI, OpenCode, MiniMax Code, and Pi. Set `AGENT_TYPE` to the corresponding backend value, and install and authenticate that CLI before starting the server.

Set `SESSION_ENABLED` to `true` and reuse the returned `session_id` on the next call. This lets an agent continue longer work across multiple requests rather than starting each invocation without the earlier session context.

Related MCP servers

All in Coding Agents All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewSub Agents MCP AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/sub-agents-mcp?style=directory)](https://allmcps.com/mcp/sub-agents-mcp)
HTML Embed
<a href="https://allmcps.com/mcp/sub-agents-mcp"><img src="https://allmcps.com/api/badge/sub-agents-mcp?style=directory" alt="Sub Agents MCP on AllMCPs" /></a>