sandbox-mcp

An MCP server that enables AI assistants to delegate complex, long-running coding tasks to OpenCode running in secure Cloudflare Sandboxes.

Why?

When using AI assistants on mobile or in short sessions, you can’t:

• Clone repositories and make multi-file code changes
• Run tests, builds, and create pull requests
• Execute long-running tasks (minutes to hours)
• Maintain state across disconnections

This MCP server solves that with fire-and-forget task delegation:

• Start a coding task, check back later
• Sessions survive disconnections and device switches
• Watch progress via web UI or poll for results
• OpenCode handles the complexity autonomously

Note: By default, this server uses Anthropic as the AI provider. To use other providers (OpenAI, Azure, Google, etc.), see Customizing the Provider.

Deploy to Cloudflare

Prerequisites

• Cloudflare account with Workers, R2, and Containers enabled
• Anthropic API key
• GitHub token (for git operations)

Setup

1. Clone and install:

git clone https://github.com/ghostwriternr/sandbox-mcp.git
cd sandbox-mcp
npm install

2. Set up secrets:

wrangler secret put PROXY_JWT_SECRET    # Any random string for signing tokens
wrangler secret put ANTHROPIC_API_KEY   # sk-ant-xxx
wrangler secret put GITHUB_TOKEN        # ghp_xxx

3. Deploy:

npm run deploy

Connect Your MCP Client

Add this server to your MCP client configuration. For Claude Desktop:

{
  "mcpServers": {
    "sandbox": {
      "url": "https://sandbox-mcp.you.workers.dev/mcp"
    }
  }
}

Usage

Once connected, your AI assistant has access to these tools:

opencode_run_task

Start a coding task. Returns immediately with a runId to check later.

{
  task: string,           // What you want done
  repository?: string,    // Git repo URL to clone
  branch?: string,        // Branch to checkout
  sessionId?: string,     // Continue existing session
}

opencode_get_result

Check the status and result of a task.

{
  runId: string           // The run ID from run_task
}

opencode_list_runs

List past task runs.

{
  sessionId?: string,     // Filter by session
  status?: string,        // Filter: started, running, completed, failed
  limit?: number,         // Max results (default 10)
}

Local Development

For local development and testing:

cp .dev.vars.example .dev.vars  # Then fill in your secrets
npm run dev                      # Start local server
npm run dev:inspect              # With MCP Inspector