High-Level Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• src/server.ts
• src/agentLoader.ts
• src/runner.ts
• README.md
• package.json
• scripts/postinstall.js

SuperAgent MCP is a Model Context Protocol (MCP) server designed to bridge MCP-compatible clients with external CLI-based AI agents, specifically Codex, Gemini, and Continue. The system acts as an orchestrator that enables parallel execution of multiple tasks, manages specialized agent system prompts, and provides a unified interface for tool discovery and invocation.

The architecture is built on a modular design where the core server handles communication via the MCP SDK, a dedicated loader manages the lifecycle and parsing of specialized agent definitions, and a runner component executes CLI commands concurrently.

Sources: README.md:3-8, src/server.ts:80-200

Core System Components

The architecture consists of three primary functional layers: the Communication Layer (MCP Server), the Management Layer (Agent Loader), and the Execution Layer (Runner).

Communication Layer (MCP Server)

The entry point of the application is the src/server.ts file, which initializes an MCP Server instance using StdioServerTransport. It defines the available tools and maps incoming requests to the appropriate execution logic.

Key responsibilities include:

• Tool definition and registration (Codex, Gemini, Continue, list-agents).
• Request validation using Zod schemas.
• Formatting execution results into human-readable text blocks for the MCP client.

Sources: src/server.ts:40-150

Management Layer (Agent Loader)

The src/agentLoader.ts module manages "specialized agents"—Markdown files containing frontmatter and system prompts. These agents are stored in the user's home directory (~/.superagent/agents).

The diagram shows the flow of agent definitions from the package source to the active tool descriptions in the server.

Sources: src/agentLoader.ts:9-30, scripts/postinstall.js:15-30

Execution Layer (Runner)

The runner (referenced in src/runner.ts) is responsible for fanning out tasks to the underlying CLI agents. It supports concurrency settings, allowing multiple prompts to be processed simultaneously. It captures raw output, duration, and success/failure statuses for each task.

Sources: src/server.ts:16-18, README.md:12-15

Data Models and Tooling

The system exposes four main tools through the MCP interface. Each tool has specific parameters and behaviors defined in the code.

Tool	Implementation	Purpose
codex	runCodexBatch	Runs Codex CLI with full system access and parallel execution.
gemini	runGeminiBatch	Runs Gemini CLI with "YOLO mode" (auto-approval).
continue	runContinueBatch	Runs Continue CLI in headless mode; requires CONTINUE_CONFIG_PATH.
list-agents	loadAgents	Returns a list of all locally available specialized agents.

Sources: src/server.ts:45-75, README.md:25-30

Agent Definition Structure

Specialized agents are defined using Markdown files with specific frontmatter fields. The parseAgentFile function extracts these fields to construct an Agent object.

export interface Agent {
  name: string;
  description: string;
  category?: string;
  systemPrompt: string;
}

Sources: src/agentLoader.ts:7-12, src/agentLoader.ts:77-105

System Workflow

The following sequence diagram illustrates the lifecycle of a tool invocation, from the client request to the final formatted response.

This diagram represents the flow of data when a user triggers an agent task through the MCP server.

Sources: src/server.ts:100-160, src/agentLoader.ts:108-120

Infrastructure and Persistence

SuperAgent maintains a local state for agent definitions to allow user customization without losing data during package updates.

• Storage Location: ~/.superagent/agents
• Synchronization: The copyAgentsIfNeeded function and postinstall.js script ensure that default agents provided by the package are seeded into the user's directory only if they do not already exist.
• Process Management: The server includes a processManager (setup in src/server.ts) to handle signal handlers for graceful shutdowns, ensuring that child CLI processes are cleaned up.

Sources: src/agentLoader.ts:14-16, src/server.ts:19-21, scripts/postinstall.js:35-45

Conclusion

The SuperAgent MCP architecture provides a high-concurrency wrapper around powerful CLI agents. By separating the concern of agent prompt management (Loader) from task orchestration (Runner), the system allows for a flexible environment where users can extend the server's capabilities simply by adding Markdown files to a local directory.