Introduction to SuperAgent MCP
Relevant source files
The following files were used as context for generating this wiki page:
SuperAgent is a Model Context Protocol (MCP) server designed to bridge MCP-compatible clients with powerful Command Line Interface (CLI) agents including Codex, Gemini, and Continue. Its primary purpose is to provide a unified interface for running multiple agent tasks in parallel, utilizing specialized system prompts, and returning structured results to the host client.
Sources: README.md:3-7
The system acts as an orchestrator that manages a library of curated agent definitions, handles the concurrent execution of CLI-based models, and ensures that local agent customizations are preserved during updates. By exposing these capabilities through standard MCP tools, SuperAgent enables complex multi-step research and code modification tasks to be handled through a single integration point.
Sources: README.md:10-14, src/server.ts:182-184
Core Architecture and Tooling
SuperAgent is built as a TypeScript-based MCP server that utilizes the @modelcontextprotocol/sdk to communicate with clients. The architecture follows a provider-runner pattern where the server defines tools that, when called, spawn underlying CLI processes to execute tasks.
Sources: package.json:20, src/server.ts:54-58
System Components
The following diagram illustrates the high-level architecture of the SuperAgent MCP server and its interaction with external CLI agents and the local filesystem.
The SuperAgent server manages communication between the client and the underlying CLI tools.
Sources: src/server.ts:63-170, README.md:17-25
Available MCP Tools
SuperAgent exposes four primary tools to the MCP client environment:
| Tool | Description | Target CLI |
|---|---|---|
codex | Executes tasks using the Codex CLI with full system access and parallel support. | codex exec |
gemini | Executes tasks using the Gemini CLI with auto-approval (YOLO mode) enabled. | gemini |
continue | Runs Continue CLI tasks in headless mode (requires CONTINUE_CONFIG_PATH). | continue |
list-agents | Returns a list of all specialized agent personas currently available in the system. | N/A (Internal) |
Sources: README.md:27-33, src/server.ts:54-72
Agent Management System
SuperAgent utilizes a flexible agent system based on Markdown files with YAML-like frontmatter. These files define the behavioral mindset and system prompts for specialized personas.
Directory Structure and Installation
Agents are stored in the user's home directory at ~/.superagent/agents. During installation, a post-install script seeds this directory with default agents provided by the package, but it will never overwrite existing files, allowing users to customize their agents locally.
Sources: src/agentLoader.ts:11, scripts/postinstall.js:15-39
Agent Data Structure
An agent is defined by four main attributes extracted from its Markdown source:
- Name: The identifier used in tool arguments.
- Description: A short summary of the agent's purpose.
- Category: A grouping for the agent (e.g., "general", "engineering", "quality").
- System Prompt: The actual behavioral instructions passed to the underlying model.
Sources: src/agentLoader.ts:7-12, src/agentLoader.ts:77-101
Execution Flow and Concurrency
When a tool like codex or gemini is invoked, the server processes a batch of inputs and manages their execution using the host's CLI tools.
Sequence of Operation
SuperAgent coordinates the retrieval of system prompts and the execution of CLI commands to fulfill client requests.
Sources: src/server.ts:98-115, src/codexAgent.ts:167-190, src/geminiAgent.ts:101-115
Technical Implementation Details
The invokeCodex and invokeGemini functions are responsible for the low-level process management:
- Process Spawning: Uses
node:child_process.spawnto run the CLI. Codex is invoked with--jsonand--dangerously-bypass-approvals-and-sandboxflags. - Input Handling: The
codexagent receives the prompt viastdin, whilegeminireceives it as a command-line argument. - Response Parsing: The server parses multi-line JSON events from
stdoutto extract the finalassistant_messageoragent_message. - Timeout Management: Tasks have a default timeout of 30 minutes to prevent hanging processes.
Sources: src/codexAgent.ts:47-52, src/codexAgent.ts:167-180, src/geminiAgent.ts:46-59, src/geminiAgent.ts:101-110
Configuration and Environment
To ensure proper functioning, specific environment variables and directory structures must be in place.
| Parameter | Purpose | Source |
|---|---|---|
CONTINUE_CONFIG_PATH | Required for the continue tool to locate the Continue YAML configuration. | README.md:46-48 |
~/.superagent/agents | The local library where .md agent files are stored and loaded. | src/agentLoader.ts:11 |
concurrency | An argument in codex/gemini tools that controls how many tasks run at once. | src/server.ts:121 |
workingDirectory | Allows agents to operate within specific project folders. | src/server.ts:62 |
Sources: README.md:46-52, src/server.ts:60-70
Conclusion
SuperAgent MCP provides a robust orchestration layer for developers looking to integrate autonomous CLI agents into their Model Context Protocol workflows. By automating the management of system prompts, handling parallel execution, and ensuring structured communication with agents like Codex and Gemini, it simplifies complex code analysis and system research tasks.