Tools Overview
Relevant source files
The following files were used as context for generating this wiki page:
The SuperAgent MCP server provides a unified interface for orchestrating multiple CLI agents through the Model Context Protocol. It acts as a bridge between MCP-compatible clients and various backend execution engines, including Codex, Gemini, and Continue. The primary purpose of these tools is to enable parallel task execution, specialized agent invocation, and structured result aggregation within a single workflow.
Sources: README.md:1-6, src/server.ts:47-66
Core Execution Tools
The server exposes three primary execution tools that interface with external CLI agents. Each tool supports parallel execution of multiple prompts and allows for the selection of specialized agent personas to modify the behavior of the underlying model.
Tool Definitions
| Tool Name | CLI Backend | Key Characteristics |
|---|---|---|
codex | Codex CLI | Full system access; supports custom CLI arguments via extraArgs. |
gemini | Gemini CLI | Operates in "YOLO mode" with auto-approval enabled for all actions. |
continue | Continue CLI | Headless mode operation; requires CONTINUE_CONFIG_PATH environment variable. |
Sources: src/server.ts:49-65, README.md:21-26
Request Flow
When a client calls an execution tool, the server validates the input using Zod schemas, dispatches tasks to specific runners, and formats the aggregated output with success/failure indicators and timing metadata.
The diagram shows the lifecycle of a tool call from client request to parallel execution and final result aggregation.
Sources: src/server.ts:100-240, src/types.ts:13-21
Specialized Agent System
SuperAgent utilizes a library of specialized "agents" which are essentially curated system prompts stored as Markdown files. These agents are synchronized to the user's local directory (~/.superagent/agents) and can be invoked using the agent parameter in any execution tool.
Agent Discovery
The list-agents tool allows clients to dynamically query the available specialized personas. This tool reads from the local filesystem, parses frontmatter from Markdown files, and returns a list of names and descriptions.
| Function | Description |
|---|---|
loadAgents() | Scans the agents directory and returns an array of Agent objects. |
parseAgentFile() | Extracts name, description, and systemPrompt from Markdown frontmatter. |
formatAgentsForDescription() | Generates a string list of agents for tool metadata. |
Sources: src/agentLoader.ts:90-138, src/server.ts:90-107
Agent Persona Examples
Specialized agents define specific behavioral mindsets and focus areas. For example:
- General-Purpose Agent: Focuses on code search and systematic exploration with a "precision and restraint" mindset.
- Deep Research Agent: Employs adaptive planning and multi-hop reasoning for complex investigations.
Sources: agents/general-purpose.md:10-18, agents/deep-research-agent.md:15-28
Data Models and Schemas
The interaction with tools is strictly governed by Zod schemas to ensure type safety and reliable CLI execution.
Input Schema (AgentPromptSchema)
Every task in an execution batch follows this structure:
| Field | Type | Description |
|---|---|---|
prompt | string | The actual instruction to send to the agent. |
agent | string? | Optional name of a specialized agent (e.g., python-expert). |
workingDirectory | string? | Path where the agent command should be executed. |
timeoutMs | number? | Maximum execution time (default 30 min, max 60 min). |
extraArgs | string[]? | Additional CLI flags (Codex tool only). |
Sources: src/types.ts:5-15
Invocation Sequence
The server handles complex orchestration, particularly when concurrency is specified, to manage system resources while executing CLI calls.
This sequence illustrates how a specialized agent prompt is retrieved and injected into the CLI runner workflow.
Sources: src/server.ts:114-140, src/agentLoader.ts:128-132, src/types.ts:56-78
Configuration and Environment
The tools rely on specific environment setups to function correctly:
- Agents Directory: Initialized at
~/.superagent/agentsviaensureAgentsDirectory(). - Continue Config: The
continuetool specifically requires theCONTINUE_CONFIG_PATHenvironment variable to locate its YAML configuration. - Concurrency: Users can specify
concurrencybetween 1 and 10 to control parallel process limits.
Sources: README.md:39-44, src/server.ts:250-255, src/types.ts:26-28
SuperAgent MCP provides a robust framework for multi-agent orchestration by abstracting CLI complexities into standard MCP tools. By combining parallel execution with a flexible, filesystem-based agent library, it enables complex automated workflows across different AI backends.