MCP Server

Overview

Coding Sandbox includes a built-in Model Context Protocol (MCP) server that allows AI agents like Claude, Copilot, and others to create, manage, and interact with sandboxes directly. The MCP server communicates with the local API under the hood.

Setup

Claude Desktop

Add the following to your Claude Desktop MCP configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "coding-sandbox": {
      "command": "csb",
      "args": ["mcp", "serve"]
    }
  }
}

Restart Claude Desktop after saving. You should see "coding-sandbox" appear in the MCP tools list.

Other MCP Clients

Any MCP-compatible client can connect to the Coding Sandbox server. Start the server manually with:

csb mcp serve

The server uses stdio transport by default. For HTTP transport:

csb mcp serve --transport http --port 3100

Available Tools

Sandbox Tools

list_sandboxes

List all sandboxes with their current status, agent type, and resource usage.

{
  "status": "running"  // optional: filter by "running", "stopped", or "all"
}

create_sandbox

Create a new sandbox with a specified agent and configuration.

{
  "name": "my-project",       // required: unique sandbox name
  "agent": "claude",          // required: agent type
  "ports": ["3000:3000"],     // optional: port mappings
  "env": {                    // optional: environment variables
    "API_KEY": "..."
  },
  "tunnel": false             // optional: enable tunnel on creation
}

start_sandbox

Start a stopped sandbox by name or ID.

{
  "sandbox": "my-project"     // sandbox name or ID
}

stop_sandbox

Gracefully stop a running sandbox.

{
  "sandbox": "my-project",
  "force": false              // optional: force kill
}

delete_sandbox

Permanently delete a sandbox and all its data.

{
  "sandbox": "my-project"
}

Tunnel Tools

enable_tunnel

Create a Cloudflare tunnel for a sandbox and return the public URL.

{
  "sandbox": "my-project"
}

{
  "tunnel_url": "https://abc123.trycloudflare.com",
  "status": "active"
}

disable_tunnel

Disconnect the tunnel for a sandbox.

{
  "sandbox": "my-project"
}

get_tunnel_url

Get the current tunnel URL and status for a sandbox.

{
  "sandbox": "my-project"
}

Execution Tools

exec_command

Execute a command inside a running sandbox container and return the output.

{
  "sandbox": "my-project",
  "command": "ls -la /workspace",
  "timeout": 30               // optional: timeout in seconds (default: 30)
}

{
  "exit_code": 0,
  "stdout": "total 24\ndrwxr-xr-x  5 user user 4096 ...",
  "stderr": ""
}

Monitoring Tools

get_logs

Retrieve container logs for a sandbox.

{
  "sandbox": "my-project",
  "tail": 100,                // optional: number of lines (default: 100)
  "since": "5m"               // optional: time window ("5m", "1h", "2d")
}

get_resource_usage

Get real-time CPU, memory, and disk usage for a sandbox or all sandboxes.

{
  "sandbox": "my-project"     // optional: omit for aggregate stats
}

Usage Examples

Once the MCP server is connected, you can ask your AI agent to manage sandboxes in natural language:

"Create a new sandbox called api-test using the Claude agent with port 8080 exposed"

"Show me all running sandboxes and their resource usage"

"Enable a tunnel for the api-test sandbox and give me the URL"

"Run 'npm install' inside the api-test sandbox"

"Get the last 50 lines of logs from api-test"

"Stop and delete the api-test sandbox"

Troubleshooting

MCP server not appearing in Claude Desktop

• Verify that csb is in your PATH by running which csb
• Check the Claude Desktop MCP log for errors
• Restart Claude Desktop after modifying the config file

Tools returning errors

• Ensure the Local API is enabled in Settings (the MCP server depends on it)
• Verify Docker is running: docker info
• Check the Coding Sandbox logs for errors (Settings > Advanced > Log file)

exec_command timing out

• Increase the timeout parameter for long-running commands
• Ensure the sandbox is in a running state
• Check container resource usage — the sandbox may be resource-constrained