MCP Integration Concepts

Relevant source files

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

• README.md
• src/server.ts
• src/codexAgent.ts
• src/geminiAgent.ts
• src/agentLoader.ts
• package.json

Introduction

The SuperAgent project serves as a Model Context Protocol (MCP) server designed to bridge MCP-compatible clients with various CLI-based agents, specifically Codex, Gemini, and Continue. Its primary purpose is to provide a unified interface for executing complex, multi-step tasks in parallel while leveraging specialized agent personas defined in Markdown format.

By implementing the MCP standard, SuperAgent allows clients to discover available tools and specialized agents dynamically. It handles the orchestration of underlying CLI processes, prompt wrapping with system instructions, and the structured return of execution results to the calling client.

Sources: README.md:1-12, src/server.ts:75-81

Core Architecture and Tooling

The integration is built upon the @modelcontextprotocol/sdk, which facilitates the communication between the server and clients via standard transports such as StdioServerTransport. The server exposes four primary tools that allow for agent interaction and management.

Tool Definitions

SuperAgent registers specific tools with the MCP SDK, each catering to a different underlying CLI engine or utility.

Tool	Engine	Description
codex	Codex CLI	Runs parallel tasks with full system access and bypasses approvals.
gemini	Gemini CLI	Runs tasks with auto-approval (YOLO mode) and JSON output formatting.
continue	Continue CLI	Executes tasks in headless mode; requires CONTINUE_CONFIG_PATH.
list-agents	Internal Utility	Returns a list of all specialized agent personas available for use.

Sources: src/server.ts:46-73, README.md:20-30

Request Flow

The following diagram illustrates the flow from an MCP Client request through the SuperAgent server to the underlying CLI agents.

The server acts as an orchestrator, handling the lifecycle of the request and the execution of external processes.

Sources: src/server.ts:89-130, src/codexAgent.ts:163-180

Specialized Agent Integration

SuperAgent uses a file-based system for managing specialized agent personas. These agents are defined as Markdown files with YAML-like frontmatter.

Agent Loading and Management

Agent definitions are stored in ~/.superagent/agents. During initialization, the server ensures this directory exists and populates it with default agents if they are missing.

• Discovery: The list-agents tool reads these files and returns their names and descriptions to the client.
• Parsing: Files are parsed to extract the name, description, and the body of the Markdown file, which serves as the systemPrompt.
• Usage: When a client invokes codex, gemini, or continue with an agent parameter, the server retrieves the corresponding system prompt to prepend it to the user's request.

Sources: src/agentLoader.ts:10-20, src/agentLoader.ts:80-110, src/server.ts:90-104

Persona Structure

An agent file typically follows this structure:

---
name: python-expert
description: Deliver production-ready Python code
category: specialized
---
# Python Expert
...System instructions...

Sources: src/agentLoader.ts:80-110, agents/python-expert.md:1-8

Execution Logic and Parallelism

One of the key features of the SuperAgent MCP integration is the ability to fan out multiple tasks in parallel.

Batch Execution

When the codex, gemini, or continue tools are called, the arguments often include a list of inputs and a concurrency limit. The server utilizes batch runners to manage these simultaneous executions, tracking durations and exit codes for each task.

Process Management

The server manages CLI invocations using Node.js spawn. It handles:

1. Input Preparation: Combining internal META_INSTRUCTION, the specialized agent's system prompt, and the user's prompt.
2. Output Parsing: Captured stdout is parsed. For Codex, it handles JSON lines; for Gemini, it attempts to extract JSON blocks containing responses and stats.
3. Timeout Handling: Each task has a default timeout (30 minutes) to prevent hanging processes.
4. Graceful Shutdown: Process managers ensure that child processes are killed if the server receives termination signals.

Sources: src/codexAgent.ts:163-190, src/geminiAgent.ts:89-115, src/server.ts:107-120

Execution Sequence

The following sequence diagram details the interaction during a Codex tool invocation:

Data Models and Schemas

The server uses Zod for input validation, ensuring that the arguments passed via MCP tools conform to the expected structure.

Field	Type	Description
inputs	Array	A list of prompt objects to execute.
concurrency	Number	Maximum number of simultaneous tasks.
agent	String	(Optional) The name of the specialized agent persona to use.
workingDirectory	String	The path where the CLI command should execute.
timeoutMs	Number	Maximum time allowed for task execution.

Sources: src/server.ts:46-68, src/codexAgent.ts:5-12, README.md:32-42

Summary

SuperAgent-MCP provides a robust framework for orchestrating AI agents through the Model Context Protocol. By centralizing agent persona management and providing a standardized tool-calling interface for Codex, Gemini, and Continue, it allows developers to integrate advanced agentic workflows into any MCP-compatible environment. The system emphasizes parallel execution, safety through timeout management, and flexibility through its Markdown-based agent library.

Sources: README.md:3-10, src/server.ts:275-285