Agent Swarm MCP server

Developers and advanced AI users need a way to extend the capabilities of primary AI assistants (like Claude Desktop, Claude Code, or Cursor) with specialized, task-specific agents.

This MCP server addresses this challenge by acting as a bridge that loads simple agent definitions (written in Markdown with frontmatter) from a directory during startup and exposes them as fully-featured, executable tools over the Model Context Protocol (MCP).

An orchestrator agent (running in Claude Desktop, Claude Code, or Cursor) can then connect to this server to discover and delegate tasks to a dynamic and expanding ecosystem of specialized agents.

Built on Claude Code SDK: This server is built on top of the Claude Code SDK, which enables running Claude Code as a subprocess to build AI-powered coding assistants and tools that leverage Claude's capabilities.

This MCP server transforms agent definition files (Markdown files with YAML frontmatter) into dynamic MCP tools that can be executed by LLMs. Each agent definition becomes a specialized tool with its own:

• System prompt - Defines the agent's role and behavior
• Configuration - Controls execution parameters, permissions, and constraints

Creating Agent Markdown Files

Agent definitions are Markdown files with YAML frontmatter that define specialized AI agents. Here is the structure:

Basic Agent Structure

---
toolName: my-specialized-agent
description: "Description of what this agent does"
maxTurns: 10
appendToSystemPrompt: true
permissionMode: "default"
cwd: "/workspace"
disallowedTools: []
model: "claude-3-5-sonnet-20241022"
---

# Agent System Prompt

This is the system prompt that defines the agent's behavior, role, and instructions.

The agent can include:
- Specific instructions for the task
- Context about the working environment
- Guidelines and constraints
- Examples of expected behavior

Configuration Properties

| Property | Type | Default | Description | | ---------------------- | -------- | ------------ | ----------------------------------------------------------------------- | | toolName | string | required | Unique identifier for the tool | | description | string | required | Human-readable description | | maxTurns | number | 10 | Maximum conversation turns (1-100) | | appendToSystemPrompt | boolean | true | Whether to append to or replace the system prompt | | permissionMode | string | "default" | Permission level: "default", "acceptEdits", "bypassPermissions", "plan" | | cwd | string | "/workspace" | Working directory for the agent | | disallowedTools | string[] | [] | List of tools that the agent cannot use | | model | string | optional | Specific model to use for this agent |

Available Claude Code Tools

Each agent has access to the following Claude Code SDK tools (unless restricted via disallowedTools):

• Agent - Delegates complex, multi-step tasks to specialized sub-agents
• Bash - Runs shell commands and scripts in the system environment
• Edit - Applies precise modifications to existing file content
• Glob - Locates files using wildcard patterns and path matching
• Grep - Searches through file content for specific text patterns
• LS - Displays directory structure and file information
• MultiEdit - Applies several changes to a single file in one operation
• NotebookEdit - Modifies cells within Jupyter notebook files
• NotebookRead - Accesses and displays Jupyter notebook structure and content
• Read - Retrieves and displays the full content of files
• TodoRead - Accesses the current session's organized task information
• TodoWrite - Creates and maintains structured task lists and workflows
• WebFetch - Retrieves content from web URLs and online resources
• WebSearch - Performs filtered web searches across specified domains
• Write - Creates new files or completely replaces existing file content

You can restrict specific tools for an agent by adding them to the disallowedTools array in the agent's frontmatter configuration.

Permission Modes

• default - Standard permissions; asks for confirmation on sensitive operations
• acceptEdits - Automatically accepts file edits without confirmation
• bypassPermissions - Bypasses most permission checks for advanced agents
• plan - Planning mode; focuses on analysis rather than execution

How the Tools Work

Tool Input Schema

All dynamically-generated tools accept the same input format:

{
  prompt: string; // The prompt to execute (1-10000 characters)
}

Tool Output

Tools return structured text content with the model's response, including any code, analysis, or other generated content.

CLI Parameters

The server supports comprehensive configuration via command-line arguments:

Transport Options

--enableHttpTransport      # Enable HTTP transport for SSE [default: false]
--enableStdioTransport     # Enable stdio transport [default: true]
--enableRestServer         # Enable REST API server [default: false]

Port Configuration

--mcpHttpPort=<port>       # Port for MCP HTTP server [default: 3001]
--restHttpPort=<port>      # Port for REST HTTP server [default: 3002]

Directory Configuration

--logDir=<path>            # Directory for logging messages (disables logging if not specified)
--agentsDir=<path>         # Directory containing agent Markdown files (uses default agent if not specified)

Usage with Claude Desktop / Claude Code / Cursor

Add this to your MCP server config JSON:

{
  "mcpServers": {
    "agent-swarm": {
      "command": "npx",
      "args": ["-y", "mcp-agent-swarm", "--agentsDir=/path/to/your/agents"]
    }
  }
}