moonbridge 0.8.0

MCP server for spawning AI coding agents (Kimi, Codex, and more)

Moonbridge

Your MCP client just got a team.

Spawn AI coding agents from Claude Code, Cursor, or any MCP client. Run 10 approaches in parallel for a fraction of the cost.

uvx moonbridge

Quick Start

1. Install at least one supported CLI:

   Adapter	Install	Authenticate
   Kimi (default)	uv tool install --python 3.13 kimi-cli	kimi login
   Codex	npm install -g @openai/codex	Set OPENAI_API_KEY

2. Add to MCP config (~/.mcp.json):

   {
     "mcpServers": {
       "moonbridge": {
         "type": "stdio",
         "command": "uvx",
         "args": ["moonbridge"]
       }
     }
   }
   

3. Use it. Your MCP client now has spawn_agent and spawn_agents_parallel tools.

Updating

Moonbridge checks for updates on startup (cached for 24h). To update manually:

# If using uvx (recommended)
uvx moonbridge --refresh

# If installed as a tool
uv tool upgrade moonbridge

Disable update checks for CI/automation:

export MOONBRIDGE_SKIP_UPDATE_CHECK=1

When to Use Moonbridge

Task	Why Moonbridge
Parallel exploration	Run 10 approaches simultaneously, pick the best
Frontend/UI work	Kimi excels at visual coding and component design
Tests and documentation	Cost-effective for high-volume tasks
Refactoring	Try multiple strategies in one request

Best for: Tasks that benefit from parallel execution or volume.

Tools

Tool	Use case
spawn_agent	Single task: "Write tests for auth.ts"
spawn_agents_parallel	Go wide: 10 agents, 10 approaches, pick the best
check_status	Verify the configured CLI is installed and authenticated
list_adapters	Show available adapters and their status

Example: Parallel Exploration

{
  "agents": [
    {"prompt": "Refactor to React hooks"},
    {"prompt": "Refactor to Zustand"},
    {"prompt": "Refactor to Redux Toolkit"}
  ]
}

Three approaches. One request. You choose the winner.

Tool Parameters

spawn_agent

Parameter	Type	Required	Description
prompt	string	Yes	Task description for the agent
adapter	string	No	Backend to use: kimi, codex (default: kimi)
model	string	No	Model override (e.g., gpt-5.2-codex)
thinking	boolean	No	Enable reasoning mode (Kimi only)
reasoning_effort	string	No	Reasoning budget: low, medium, high, xhigh (Codex only)
timeout_seconds	integer	No	Override default timeout (30-3600)

spawn_agents_parallel

Parameter	Type	Required	Description
agents	array	Yes	List of agent configs (max 10)
agents[].prompt	string	Yes	Task for this agent
agents[].adapter	string	No	Backend for this agent
agents[].model	string	No	Model override for this agent
agents[].thinking	boolean	No	Enable reasoning (Kimi only)
agents[].reasoning_effort	string	No	Reasoning budget (Codex only)
agents[].timeout_seconds	integer	No	Timeout for this agent

Response Format

All tools return JSON with these fields:

Field	Type	Description
status	string	success, error, timeout, auth_error, or cancelled
output	string	stdout from the agent
stderr	string|null	stderr if any
returncode	int	Process exit code (-1 for timeout/error)
duration_ms	int	Execution time in milliseconds
agent_index	int	Agent index (0 for single, 0-N for parallel)
message	string?	Human-readable error context (when applicable)
raw	object?	Optional structured metadata (e.g., sandbox diff)

Configuration

Environment Variables

Variable	Description
MOONBRIDGE_ADAPTER	Default adapter (default: kimi)
MOONBRIDGE_TIMEOUT	Default timeout in seconds (30-3600)
MOONBRIDGE_MAX_AGENTS	Maximum parallel agents
MOONBRIDGE_ALLOWED_DIRS	Colon-separated allowlist of working directories
MOONBRIDGE_STRICT	Set to 1 to require ALLOWED_DIRS (exits if unset)
MOONBRIDGE_SANDBOX	Set to 1 to run agents in a temp copy of cwd
MOONBRIDGE_SANDBOX_KEEP	Set to 1 to keep sandbox dir for inspection
MOONBRIDGE_SANDBOX_MAX_DIFF	Max diff size in bytes (default 500000)
MOONBRIDGE_SANDBOX_MAX_COPY	Max sandbox copy size in bytes (default 500MB)
MOONBRIDGE_LOG_LEVEL	Set to DEBUG for verbose logging

Troubleshooting

"CLI not found"

Install the CLI for your chosen adapter:

# Kimi
uv tool install --python 3.13 kimi-cli
which kimi

# Codex
npm install -g @openai/codex
which codex

"auth_error" responses

Authenticate with your chosen CLI:

# Kimi
kimi login

# Codex
export OPENAI_API_KEY=sk-...

Timeout errors

Adapters have sensible defaults: Codex=1800s (30min), Kimi=600s (10min).

For exceptionally long tasks, override explicitly:

{"prompt": "...", "timeout_seconds": 3600}

Or set per-adapter defaults via environment:

export MOONBRIDGE_CODEX_TIMEOUT=2400  # 40 minutes
export MOONBRIDGE_KIMI_TIMEOUT=900    # 15 minutes

Timeout Best Practices

Task Type	Recommended
Quick query, status	60-180s
Simple edits	300-600s
Feature implementation	1200-1800s
Large refactor	1800-3600s

Priority resolution: explicit param > adapter env > adapter default > global env > 600s fallback

"MOONBRIDGE_ALLOWED_DIRS is not set" warning

By default, Moonbridge warns at startup if no directory restrictions are configured. This is expected for local development. For shared/production environments, set allowed directories:

export MOONBRIDGE_ALLOWED_DIRS="/path/to/project:/another/path"

Sandbox Mode (Copy-on-Run)

Enable sandbox mode to run agents in a temporary copy of the working directory:

export MOONBRIDGE_SANDBOX=1

When enabled:

• Agents run in a temp copy of cwd.
• Host files stay unchanged by default.
• A unified diff + summary is included in raw.sandbox.

Optional:

export MOONBRIDGE_SANDBOX_KEEP=1       # keep temp dir
export MOONBRIDGE_SANDBOX_MAX_DIFF=200000
export MOONBRIDGE_SANDBOX_MAX_COPY=300000000

Limitations: this is not OS-level isolation. Agents can still read/write arbitrary host paths if they choose to. Use containers/VMs for strong isolation.

To enforce restrictions (exit instead of warn):

export MOONBRIDGE_STRICT=1

Permission denied on working directory

Verify the directory is in your allowlist:

export MOONBRIDGE_ALLOWED_DIRS="/path/to/project:/another/path"

Debug logging

Enable verbose logging:

export MOONBRIDGE_LOG_LEVEL=DEBUG

Platform Support

macOS and Linux only. Windows is not supported.

License

MIT. See LICENSE.