MCP Integration

Agent Sandbox provides an MCP (Model Context Protocol) Server, enabling AI IDEs and tools to operate sandboxes directly.

What Is MCP

MCP (Model Context Protocol) is an open protocol that allows AI models to interact with external tools and services. The Agent Sandbox MCP Server runs over STDIO transport with JSON-RPC 2.0 protocol, providing sandbox operation capabilities to AI assistants. A Streamable HTTP transport is also available for remote deployments (see below).

Requirements

npm install -g @agent-sandbox/cli   # abx CLI + MCP STDIO server
export ABX_SANDBOX_API_KEY=your-api-key     # or: abx config set sandbox_api_key your-api-key

Install to IDE

Cursor

abx mcp install --target cursor

Writes an agent-sandbox entry into ~/.cursor/mcp.json, then restart Cursor.

Claude Desktop

abx mcp install --target claude

Writes into claude_desktop_config.json (location depends on OS), then restart Claude Desktop.

VS Code

abx mcp install --target vscode

Writes the workspace .vscode/mcp.json servers entry (type: stdio), then reload the VS Code window. That file is often committed, so the installer does not copy the API key into it; abx mcp start reads the key from the environment or ~/.abx.

All targets register the same STDIO command: abx mcp start. The command is the absolute path of the running abx executable (or node <absolute path of abx.js> when abx cannot be found), so an IDE with a minimal PATH can still start the server. The installer merges into existing config files — other MCP servers you have configured are preserved. A config file that is not strict JSON (comments or trailing commas) is left untouched. Cursor and Claude user-level configs embed the API key in env when one is available. That key follows Credential resolution: the process environment, then ./.env, then ~/.abx. ABX_SANDBOX_BASE_URL and SANDBOX_REGION are copied only when the process environment sets them; a region saved with abx config set region is read again when abx mcp start runs.

Check Installation Status

abx mcp status
# server, transport, tool list, auth_configured, installed_<ide> flags

abx --json mcp status

Available Tools

The MCP Server provides 7 tools:

Naming clarification: The MCP tool run_command runs the command via sh -c (sandbox.commands.run(..., shell=True) in the SDK). It is unrelated to the deprecated SDK method Sandbox.run_command(), which dispatches named custom commands — use Sandbox.custom() for that purpose.

Default sandbox: create_sandbox makes that sandbox the default, so a later write_file / run_code / kill_sandbox that omits sandbox_id uses the sandbox just created. If there is no default yet, the first tool call that omits sandbox_id lazily creates one. An omitted template uses the server template (code-interpreter-v1 for abx mcp start). Each use extends the sandbox lifetime by the timeout it was created with. Every sandbox in the session is destroyed when the IDE closes the server (STDIO) or on DELETE /mcp / idle timeout (HTTP).

Manually Start the MCP Server (STDIO)

The MCP Server is usually started automatically by the IDE. A manual process sits on stdin waiting for JSON-RPC; that wait is the running state. On startup it writes the transport, protocol, template, whether an API key is configured, the tool list, and how to stop to stderr (stdout stays JSON-RPC, and the secret itself is not printed):

abx mcp start

Stop it from another terminal:

abx mcp stop

abx mcp stop sends SIGTERM to the recorded pid. A foreground STDIO process also stops on Ctrl-C. The pid file and log live under ~/.abx/run/ (mcp-server.json, mcp-server.log); tests can point ABX_MCP_RUNTIME_DIR somewhere else. abx mcp status reports mcp_running for this local process.

Background HTTP:

abx mcp start --http --background
abx mcp stop

The parent prints the pid, http://127.0.0.1:9000/mcp, and the log path, then returns. The API key and token go into the child environment, not its argv. --quiet skips these notes.

In STDIO mode the server speaks newline-delimited JSON-RPC 2.0 on stdin/stdout. You can smoke-test it without an IDE (the notes stay on stderr, so the pipe is still JSON):

# initialize + tools/list over a pipe; the server replies on stdout
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | abx mcp start | head -n 2

Remote Server (Streamable HTTP)

For team sharing or remote access, run the MCP Server as a Streamable HTTP service instead of STDIO.

Run Locally

Run the Streamable HTTP server from the CLI (abx mcp start --http, options in the table below):

export ABX_MCP_AUTH_TOKEN=replace_me   # Bearer token (omit on loopback to disable auth)
export ABX_SANDBOX_API_KEY=your-api-key

abx mcp start --http --host 0.0.0.0 --port 9000

Endpoints: POST /mcp (JSON-RPC), DELETE /mcp (session termination), GET /health (health check). GET /mcp returns 405 (SSE notifications are not implemented; the Streamable HTTP spec uses 405 rather than 501). A request that sends Origin from anywhere other than localhost or ABX_MCP_ALLOWED_ORIGINS is rejected with 403.

Bearer Token Authentication

The three entry points use different credentials:

When ABX_MCP_AUTH_TOKEN (or auth_token) is set, every /mcp request must carry:

Authorization: Bearer <token>

• Loopback with the token unset → authentication disabled, and the process warns
• Token set but empty → fails closed: every request is rejected with 401
• FC artifact with the token unset or empty → the process refuses to start

Tokens are compared with constant-time comparison. Generate one with openssl rand -base64 32 or let abx mcp deploy --generate-token create one.

Client Configuration (Remote)

{
  "mcpServers": {
    "agent-sandbox-remote": {
      "url": "http://your-server:9000/mcp",
      "headers": {
        "Authorization": "Bearer replace_me"
      }
    }
  }
}

Generate an FC Deployment Artifact

abx mcp deploy produces a ready-to-package artifact for Alibaba Cloud Function Compute. It does not call the FC API — you create the function manually via the console or SDK.

abx mcp deploy \
  --generate-token \
  --api-key $ABX_SANDBOX_API_KEY \
  --output-dir ./mcp-artifact

The artifact directory contains:

The command prints: manual FC deployment steps (package → create function → create HTTP trigger → enable Mcp-Session-Id affinity if supported) and an IDE config template pointing at <FC_HTTP_TRIGGER_URL>/mcp with a masked Bearer token.

Security: config.yaml contains your API key and Bearer token. Do not commit it to version control.

After deployment, configure clients with the trigger URL:

{
  "mcpServers": {
    "agent-sandbox-remote": {
      "url": "https://<FC_HTTP_TRIGGER_URL>/mcp",
      "headers": { "Authorization": "Bearer <BEARER_TOKEN>" }
    }
  }
}

Usage Examples

Using in Cursor

After installing MCP, the model can automatically invoke Agent Sandbox tools in Cursor's AI chat:

1. Code execution: "Run this Python code in a sandbox and show me the output"
2. Environment setup: "Create a sandbox, install flask and sqlalchemy, then run my project"
3. File operations: "Write this file to the /app directory in the sandbox"
4. Debug assistance: "Run pip list in the sandbox to see what packages are installed"

Typical Workflow

sequenceDiagram
    participant User as User
    participant AI as AI Assistant
    participant MCP as MCP Server / Sandbox

    User->>AI: Help me test this code in a sandbox
    AI->>MCP: create_sandbox
    MCP-->>AI: sandbox_id
    AI->>MCP: write_file — write code file
    AI->>MCP: run_code — execute code
    MCP-->>AI: execution result
    AI->>MCP: read_file — read result
    AI->>MCP: kill_sandbox — cleanup
    AI-->>User: return test result

Run a Quick Code Snippet (HTTP, curl)

# 1. initialize (creates a session; capture Mcp-Session-Id)
curl -s http://localhost:9000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer replace_me" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

# 2. call a tool with the session header
curl -s http://localhost:9000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer replace_me" \
  -H "Mcp-Session-Id: <SESSION_ID_FROM_STEP_1>" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"run_code","arguments":{"code":"print(1+1)"}}}'

# 3. terminate the session (destroys its sandboxes)
curl -s -X DELETE http://localhost:9000/mcp \
  -H "Authorization: Bearer replace_me" \
  -H "Mcp-Session-Id: <SESSION_ID_FROM_STEP_1>"

Troubleshooting

More general issues: see the Troubleshooting guide and error codes.

Technical Details

• Transport protocols: STDIO (newline-delimited JSON-RPC 2.0, protocol version 2024-11-05) and Streamable HTTP (spec 2025-06-18). initialize negotiates each transport's supported version — a supported requested protocolVersion is echoed back; missing or unsupported requests fall back to the transport's own version (so HTTP health and initialize both report 2025-06-18)
• Sandbox management: the server internally maintains a SandboxManager per session that manages the lifecycle of multiple sandbox instances
• Default template: code-interpreter-v1 via abx mcp start; base for the HTTP app and abx mcp deploy artifacts. create_sandbox uses that server template when template is omitted
• STDIO: one message may be up to 8 MiB. A longer line is rejected and the process keeps serving. ping is answered while a tool call is still running
• HTTP sessions: idle TTL 3600 s, max 100 concurrent sessions per process, capacity exhaustion returns 503

Next Steps

• CLI Tutorial — Complete CLI tutorial
• CLI Reference — Detailed MCP command reference
• MCP Server Design — Tools, transports, and FC deployment architecture

Related SDK documentation

Running the Python implementation of the MCP server — python -m agent_sandbox.agent.mcp, the ASGI entry point (uvicorn agent_sandbox.agent.mcp_http:asgi_app) and create_mcp_app() — is covered by the SDK's MCP Integration guide and SDK Usage Guide in the python-sdk repository.