Configuration & Environment
Relevant source files
The following files were used as context for generating this wiki page:
The SuperAgent MCP server serves as a bridge between Model Context Protocol (MCP) clients and various CLI-based AI agents, specifically Codex, Gemini, and Continue. Its configuration and environment management revolve around establishing a secure, parallelized execution environment for these tools while managing a library of specialized agent personas defined in Markdown files.
The system relies on specific environment variables for tool-specific configurations (such as the Continue CLI) and utilizes a local filesystem directory for storing and customizing agent system prompts. It is designed to be deployed as an MCP server via Stdio transport, allowing it to integrate seamlessly into host applications like Claude Desktop.
Sources: README.md:3-8, src/server.ts:251-255
Core Environment & Setup
SuperAgent requires a Node.js runtime (version 18 or newer) and manages its dependencies and executable paths through standard NPM conventions. The server is primarily distributed as an ESM module.
Key Environment Variables
The application behavior is influenced by the following environment configurations:
| Variable | Requirement | Description |
|---|---|---|
CONTINUE_CONFIG_PATH | Required for continue tool | Absolute path to the Continue configuration file (YAML/JSON). |
PATH | System Default | Must include paths to codex, gemini, and continue CLI binaries. |
HOME (or ~) | Required | Used to resolve the ~/.superagent/agents directory. |
Sources: README.md:46-51, src/agentLoader.ts:10, package.json:20-25
Runtime Configuration
The server initializes by setting up signal handlers for graceful shutdown and ensuring the existence of the agents directory. It then establishes a connection via StdioServerTransport.
The initialization flow ensures that the environment is prepared before the MCP server begins accepting tool calls.
Sources: src/server.ts:245-257, src/agentLoader.ts:56-62
Agent Library Management
SuperAgent utilizes a file-based system for managing specialized agents. These agents are defined as Markdown files containing YAML-like frontmatter for metadata and a body that serves as the system prompt.
The Agents Directory
Agents are stored in ~/.superagent/agents. During installation or server startup, the system performs a sync operation to ensure standard agents are available.
- Initialization Logic: If the
~/.superagent/agentsdirectory does not exist, it is created. - Seeding: Files bundled with the package are copied to the user's home directory only if they do not already exist, allowing users to customize prompts without them being overwritten by updates.
Sources: src/agentLoader.ts:10-53, README.md:40-44
Agent File Structure
Files must follow a specific format to be correctly parsed by the agentLoader.ts.
| Component | Description |
|---|---|
| Frontmatter | Block delimited by --- containing name, description, and optional category. |
| Body | The raw text used as the systemPrompt for the underlying CLI tool. |
Sources: src/agentLoader.ts:65-95
Tool-Specific Configurations
Each integrated CLI tool has specific execution requirements and environment configurations passed through the MCP interface.
Codex Execution Environment
The Codex tool is invoked with specific flags to ensure it operates correctly within a non-interactive MCP context.
- Bypass Mode: Uses
--dangerously-bypass-approvals-and-sandboxto allow the agent full system access. - Output Format: Uses
--jsonto facilitate structured event parsing. - Prompt Injection: Combines a hardcoded
META_INSTRUCTIONwith the agent-specificsystemPromptand the user'sprompt.
Sources: src/codexAgent.ts:47-58, src/codexAgent.ts:167-171
Parallelism and Concurrency
The server manages parallel task execution by batching inputs. Each tool configuration supports a concurrency parameter, which controls how many CLI processes are spawned simultaneously.
Process Management & Cleanup
Because SuperAgent spawns long-running CLI processes, it includes a processManager to handle lifecycle events. This prevents orphaned processes (zombies) if the MCP server or the host client crashes.
- Registration: Every spawned child process is registered via
registerProcess. - Signal Handling: The server listens for
SIGINT,SIGTERM, and other termination signals. - Cleanup: Upon termination, the server kills all registered child processes (using
SIGKILLif a timeout is exceeded).
Sources: src/codexAgent.ts:141-142, src/server.ts:246, src/codexAgent.ts:182-185
Summary
The Configuration & Environment of SuperAgent MCP is designed for portability and extensibility. By combining standard environment variables for tool paths (like CONTINUE_CONFIG_PATH) with a local Markdown-based agent library in ~/.superagent/agents, it allows developers to maintain specialized AI personas that can be invoked across different CLI backends. The architecture ensures reliability through robust process management and a systematic approach to agent prompt synchronization.