Troubleshooting & FAQ

Relevant source files

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

• README.md
• src/server.ts
• src/agentLoader.ts
• src/codexAgent.ts
• agents/technical-writer.md
• package.json

Introduction

The SuperAgent MCP server facilitates parallel execution and orchestration of CLI-based agents like Codex, Gemini, and Continue within the Model Context Protocol (MCP) framework. This page provides technical guidance for resolving common issues related to agent invocation, configuration environment variables, and filesystem management.

The system relies on a bridge between standard MCP tool calls and the local execution of CLI binaries. Most troubleshooting steps involve verifying the presence of external dependencies, environment configurations, and the integrity of the local agent library located in the user's home directory.
Sources: README.md:1-10, src/server.ts:246-258

Execution & Lifecycle Management

Process Timeouts

Each agent task is subject to a default timeout to prevent hanging processes. If a task exceeds this limit, the server kills the child process with a SIGKILL signal and returns an error response.

The diagram shows the internal logic for handling long-running agent tasks and the fallback mechanism for process termination.
Sources: src/codexAgent.ts:140-160

Error Identification

When an agent fails, the MCP server provides detailed feedback including exit codes, duration, and error streams.

Field	Description	Source
status	"ok" or "failed"	src/server.ts:114-140
exitCode	The process exit code from the CLI (e.g., Codex)	src/codexAgent.ts:26-34
stderr	Standard error output from the underlying tool	src/codexAgent.ts:165-170
durationMs	Total execution time before failure or success	src/server.ts:117

Configuration Issues

Environment Variables

Certain tools require specific environment variables to be passed through the MCP client to the server.

• Continue Tool: Requires CONTINUE_CONFIG_PATH to point to a valid configuration YAML file. Without this, the continue tool will fail during invocation.
• Codex Tool: Runs with the --dangerously-bypass-approvals-and-sandbox flag by default to ensure full system access for automation.
  Sources: README.md:41-45, src/server.ts:64-68, src/codexAgent.ts:46-51

Agent Library Sync

The server maintains a local repository of specialized agents at ~/.superagent/agents. Issues often arise if this directory is inaccessible or if agent files are improperly formatted.

The sequence diagram illustrates the ensureAgentsDirectory and copyAgentsIfNeeded logic that runs during server startup.
Sources: src/agentLoader.ts:43-75, src/server.ts:251

Parsing & Tool Discovery

Failed Agent Parsing

Agents are defined in Markdown files with specific YAML frontmatter. If an agent does not appear in the list-agents output, verify the following structure:

• Frontmatter: Must be enclosed in --- blocks.
• Required Fields: name and description must be present.
• Body: The Markdown content after the frontmatter serves as the system prompt.
  Sources: src/agentLoader.ts:77-105

Tool Schema Mismatches

The server uses Zod to validate incoming tool arguments. If a client receives a "Validation Error", ensure the input matches the expected schema for the tool (e.g., CodexInvokeSchema).

// Example Codex schema requirements
const CodexInvokeSchema = z.object({
  inputs: z.array(z.object({
    prompt: z.string(),
    workingDirectory: z.string().optional(),
    agent: z.string().optional()
  })),
  concurrency: z.number().default(1),
  // ...
});

Sources: src/server.ts:101-105, src/codexAgent.ts:5-13

FAQ

Q: Where are the default system prompts stored?
A: They are initially shipped within the npm package and copied to ~/.superagent/agents/ upon first run or installation.
Sources: README.md:37-40, src/agentLoader.ts:10-12

Q: Why does the codex tool have "full system access"?
A: The server invokes codex exec with the --dangerously-bypass-approvals-and-sandbox flag to allow the agent to perform multi-step tasks like code modification and system exploration without manual approval interrupts.
Sources: src/codexAgent.ts:46-51, src/server.ts:54-58

Q: How do I add a custom specialized agent?
A: Create a new .md file in ~/.superagent/agents with the appropriate frontmatter. The server will automatically load it and make it available via the agent parameter in the codex, gemini, or continue tools.
Sources: README.md:37-40, src/agentLoader.ts:114-130

Summary

Troubleshooting SuperAgent MCP primarily involves verifying the local filesystem state for agents and ensuring the host environment has the required CLI binaries and environment variables. By monitoring the detailed success/failure output provided in the MCP tool response, developers can quickly identify if an issue is related to process timeouts, permission restrictions, or configuration omissions.