@metyatech/agents-mcp

Fork note: this is a metyatech-maintained fork of @swarmify/agents-mcp extracted into a standalone repository for improved Windows compatibility.

SubAgents and Swarms for any MCP client. Spawn parallel agents from Claude, Codex, Gemini, or any tool that speaks MCP.

Part of Swarmify - multi-agent coding in your IDE.

Upstream | VS Code Extension | Demo Video

Cross-Platform Agent Orchestration

                         MCP Protocol
                              |
        +---------------------+---------------------+
        |                     |                     |
   Claude Code             Codex                Gemini CLI
   (MCP Client)         (MCP Client)          (MCP Client)
        |                     |                     |
        +---------------------+---------------------+
                              |
                    +-------------------+
                    |   agents-mcp      |
                    | (MCP Server)      |
                    +-------------------+
                              |
        +---------------------+---------------------+
        |                     |                     |
   claude CLI            codex CLI            gemini CLI
   (SubAgent)            (SubAgent)           (SubAgent)

Any client can spawn any agent. Claude can spawn Codex. Gemini can spawn Claude. Cursor can spawn all three. The MCP protocol is the universal interface that makes this interoperability possible.

SubAgents and Swarms

This server enables two multi-agent patterns:

SubAgents - Hierarchical delegation where an orchestrator spawns specialized agents for specific tasks. Each agent works in isolation and reports back to the parent.

Swarms - Multiple agents working in parallel on different parts of a problem. The orchestrator coordinates, assigns non-overlapping files, and synthesizes results.

Both patterns use the same four tools. The orchestrator decides the pattern.

Why Cross-Platform Matters

Without this server, each agent is siloed:

• Claude Code has built-in subagents, but only Claude
• Codex has no native subagent support
• Gemini CLI has no native subagent support

With this server, every MCP client gets the same capabilities. Mix models based on their strengths:

Workflow	How It Works
Opus for planning, Codex for speed	Use Claude Opus as orchestrator to design architecture, spawn Codex agents for fast, cheap implementation
Claude for research, Cursor for code	Claude explores codebase and plans approach, Cursor (Composer) writes the code
Parallel specialists	Claude reviews security while Codex adds validation - simultaneously
Codex spawning Claude	When Codex hits something needing deeper reasoning, it spawns Claude

You control the cost tradeoffs. Expensive models for planning, fast models for execution.

4 tools: Spawn, Status, Stop, Tasks 3 modes: plan (read-only), edit (can write), ralph (autonomous) Background processes: Agents run headless, survive IDE restarts

Quick Start

# Claude Code
claude mcp add --scope user Swarm -- npx -y --package git+https://github.com/metyatech/agents-mcp.git#main agents-mcp

# Codex
codex mcp add swarm -- npx -y --package git+https://github.com/metyatech/agents-mcp.git#main agents-mcp

# Gemini CLI
gemini mcp add Swarm -- npx -y --package git+https://github.com/metyatech/agents-mcp.git#main agents-mcp

# OpenCode
opencode mcp add
# Name: Swarm, Command: npx -y --package git+https://github.com/metyatech/agents-mcp.git#main agents-mcp

The server auto-discovers which agent CLIs you have installed. Once connected, your agent gains the ability to spawn and coordinate other agents.

What It Costs

This server is free and open source.

Each agent uses your own API keys. Spawning 3 Claude agents means 3x your normal Claude API cost. No hidden fees.

Example: Swarm in Action

After installing, try this in Claude Code:

Spawn a codex agent to add input validation to src/api/users.ts, and a claude agent to review the security implications

The orchestrating agent spawns both agents in parallel:

Claude Code (Orchestrator)
        |
        +-- Spawn(codex, "add input validation to src/api/users.ts")
        |         |
        |         v
        |   Codex Agent -----> modifies src/api/users.ts
        |
        +-- Spawn(claude, "review security implications")
                  |
                  v
            Claude Agent -----> analyzes changes, reports findings
        |
        +-- Status(task_name) -----> polls for completion
        |
        v
   Synthesizes results from both agents

The orchestrator decides when to spawn, what to assign, and how to combine results. The MCP server just provides the tools.

API Reference

Spawn

Spawn(task_name, agent_type, prompt, mode?, cwd?, effort?)

Start an agent on a task. Returns immediately with agent ID.

Parameter	Required	Description
task_name	Yes	Groups related agents (e.g., "auth-feature")
agent_type	Yes	claude, codex, gemini, or cursor
prompt	Yes	The task for the agent
mode	No	plan (default), edit, or ralph
cwd	No	Working directory
effort	No	fast, default, or detailed

Status

Status(task_name, filter?, since?)

Get agent progress: files changed, commands run, last messages.

Parameter	Required	Description
task_name	Yes	Task to check
filter	No	running (default), completed, failed, stopped, all
since	No	ISO timestamp for delta updates

Stop

Stop(task_name, agent_id?)

Stop all agents in a task, or a specific agent by ID.

Tasks

Tasks(limit?)

List all tasks sorted by most recent activity. Defaults to 10.

Modes

Mode	File Access	Auto-loop?	Use Case
plan	Read-only	No	Research, code review
edit	Read + Write	No	Implementation, fixes
ralph	Full	Yes	Autonomous via RALPH.md

Default is plan for safety. Pass mode='edit' when agents need to modify files.

Ralph Mode

Ralph mode spawns one agent with full permissions to autonomously work through tasks in a RALPH.md file. The agent reads the file, picks tasks logically, marks them complete, and continues until done.

## [ ] Implement user authentication

Add JWT-based auth to the backend.

### Updates

---

## [x] Add rate limiting

Protect API endpoints.

### Updates

- Added sliding window counter

Spawn(mode='ralph', cwd='./my-project', prompt='Build the auth system')

CLI Commands

In addition to running as an MCP server, agents-mcp exposes CLI subcommands for monitoring agents without requiring an active MCP connection. This is useful for orchestrators that need to track background agents.

agents-mcp status

Instant, non-blocking status check. Reads agent metadata directly from ~/.agents/swarm/agents/ and returns JSON immediately.

agents-mcp status --task <name>

Option	Required	Description
--task <name>	Yes	Task name to check
--help	No	Show help

Output: JSON summary of all agents in the task (status, files changed, last messages).

agents-mcp wait

Polls until all agents in the task complete or a timeout is reached.

agents-mcp wait --task <name> [--timeout <ms>]

Option	Required	Description
--task <name>	Yes	Task name to wait on
--timeout <ms>	No	Maximum wait time in milliseconds (default: 300000, max: 600000)
--help	No	Show help

Exit codes

Code	Meaning
0	All agents completed successfully
1	Timeout or error
2	No agents found for the task

Non-blocking monitoring pattern

For platforms that need to stay responsive while waiting for agents, run wait in the background:

# Claude Code: background monitoring while staying responsive to user input
Bash(run_in_background=true, command="agents-mcp wait --task my-task --timeout 300000")

# Any platform: instant non-blocking check
agents-mcp status --task my-task

This pattern lets orchestrators dispatch agents and continue handling input while background monitoring notifies when work is done.

Default behavior (no subcommand)

Running agents-mcp without a subcommand starts the MCP server as before — existing behavior is unchanged.

agents-mcp   # starts MCP server

What This Server Does NOT Do

Not This	That's The Orchestrator's Job
Scheduling	Decides when to spawn which agents
Task assignment	Writes prompts, defines what to do
Conflict resolution	Assigns non-overlapping files to agents
Intelligence	Pure infrastructure - no decision-making

The server is a tool. Your orchestrating agent (Claude, etc.) decides how to use it.

Supported Agents

Agent	CLI	Best For
Claude	claude	Complex research, orchestration
Codex	codex	Fast implementation
Gemini	gemini	Multi-system changes
Cursor	cursor-agent	Debugging, tracing
OpenCode	opencode	Provider-agnostic, open source

Under the Hood

How Agents Communicate

Agents communicate through the filesystem, not shared memory:

Orchestrator                     SubAgent
     |                              |
     +-- Spawn ------------------>  |
     |                              |
     |                         writes to stdout
     |                              |
     |                         ~/.agents/swarm/agents/{id}/stdout.log
     |                              |
     +-- Status -----------------> reads log, parses events
     |                              |
     <-- files changed, messages ---+
     |                              |
     +-- (repeat until done) -------+

Each agent writes to its own log file (stdout.log). The Status tool reads these logs, normalizes events across different agent formats, and returns a summary. This design means:

• Persistence: Agents survive IDE restarts. Reconnect via Status/Tasks.
• Debugging: Full logs available at ~/.agents/swarm/agents/{id}/
• No shared state: Agents don't talk to each other directly. The orchestrator coordinates.

Storage

Data lives at ~/.agents/:

~/.agents/
  config.json              # Agent configuration
  agents/
    {agent-id}/
      metadata.json        # task, type, mode, status
      stdout.log           # Raw agent output

Plan mode is read-only:

• Claude: --permission-mode plan
• Codex: sandboxed
• Gemini/Cursor: no auto-approve

Edit mode unlocks writes:

• Claude: acceptEdits
• Codex: --full-auto
• Gemini: --yolo
• Cursor: -f

Development

npm install          # install dependencies (also sets up husky pre-commit hooks via prepare)
npm run verify       # lint + format:check + typecheck + test + build
npm run format       # auto-fix formatting with prettier
npm test             # run tests only
npm run build        # compile TypeScript

A pre-commit hook (npm run verify) runs automatically on every commit via husky. Commits that fail lint, formatting, typecheck, tests, or build are blocked.

Configuration

Config lives at ~/.agents/swarm/config.json. See AGENTS.md for full config reference.

Environment Variables

Variable	Description
AGENTS_MCP_DEFAULT_MODE	Default mode (plan or edit)
AGENTS_MCP_RALPH_FILE	Task file name (default: RALPH.md)
AGENTS_MCP_DISABLE_RALPH	Set true to disable ralph mode

Works great with the extension

This MCP server works standalone with any MCP client. For the best experience - full-screen agent terminals, session persistence, fast navigation - install the Agents extension for VS Code/Cursor.

License

MIT