boxkite

Integration

MCP server

An MCP (Model Context Protocol) server over a hosted control-plane — lets any MCP-compatible client (Claude Code, Claude Desktop, Codex, Cursor) attach a real sandboxed code-execution backend as a native tool source, with zero custom integration code. Built on top of the Python SDK — adds no HTTP logic of its own, only the MCP tool surface.

Install

terminal
pip install boxkite-client
pip install boxkite-mcp

Configure

Two environment variables, read at startup. The process fails fast with a clear error if either is missing:

  • BOXKITE_BASE_URL — base URL of the control-plane
  • BOXKITE_API_KEY — a bxk_live_... API key for your account

Rather than editing a client's config file by hand, boxkite mcp init <target> writes this entry for you (Claude Code, Cursor, Windsurf, Claude Desktop, or Codex), using the base_url/api_key already saved by boxkite signup— merges into that file's existing config rather than overwriting it (a TOML table for Codex's ~/.codex/config.toml, JSON for every other target):

terminal
boxkite mcp init claude-code
# Added the boxkite MCP server entry in .mcp.json.
# Restart your MCP client to pick up the change.

Run

terminal
BOXKITE_BASE_URL=https://your-control-plane.example.com \
BOXKITE_API_KEY=bxk_live_... \
boxkite-mcp

Speaks MCP over stdio — point an MCP client's config at the boxkite-mcp command.

Hosted MCP & OAuth

Instead of running a local stdio MCP subprocess on your machine, a boxkite control-plane deployment can expose a remote, Streamable HTTP transport MCP endpoint directly.

To configure an MCP client (such as Claude Desktop) to connect directly to the hosted control-plane over Streamable HTTP, with your API key as a bearer token:

claude_desktop_config.json
{
  "mcpServers": {
    "boxkite": {
      "url": "https://your-control-plane.example.com/mcp",
      "headers": {
        "Authorization": "Bearer bxk_live_..."
      }
    }
  }
}

Codex uses TOML instead of JSON, and reads the bearer token from an environment variable rather than a literal value in the config file — set BOXKITE_API_KEY in your shell, then:

~/.codex/config.toml
[mcp_servers.boxkite]
url = "https://your-control-plane.example.com/mcp"
bearer_token_env_var = "BOXKITE_API_KEY"

If your deployment has MCP OAuth enabled (BOXKITE_MCP_OAUTH_ENABLED=true), client applications can authenticate users dynamically using standard OAuth 2.1 authorization flows (RFC 8414 and RFC 9728) instead of requiring a static API key.

Tools

Every per-sandbox tool takes session_id as a parameter — the calling agent owns the full lifecycle: create a sandbox, run several things in it, destroy it, all within one conversation.

  • create_sandbox(label?, size?, storage_gb?, lifetime_minutes?, count?) — see Sandboxes for what each param does
  • get_sandbox(session_id)— look up one sandbox's status
  • list_sandboxes(active_only?)— list the account's sandboxes
  • destroy_sandbox(session_id) — tear one down
  • exec(session_id, command, timeout?) — see Process & exec
  • file_create/view/str_replace/ls/glob/grep — see File system
  • create_sandbox_image/get_sandbox_image/list_sandbox_images/delete_sandbox_image — see Custom sandbox images (opt-in declarative builder, off by default)
  • create_sandbox_volume/get_sandbox_volume/list_sandbox_volumes/delete_sandbox_volume — see Independent storage volumes (opt-in PVC-backed storage, off by default)

The sandbox's own isolation is the trust boundary, not this MCP layer

This server itself applies no argument validation of its own — execruns whatever shell command it's given, and view/file_create/str_replaceoperate on any path. That's correct for a code-execution sandbox product — the isolation boundary is the Kubernetes sandbox itself, not this MCP server's argument validation.

If your account has a persisted command allowlist set (see boxkite allowlist in the hosted & CLI guide ↗, or the SDKs' get_allowed_commands/set_allowed_commands), it's enforced upstream by the control-plane on every execcall this server makes — an unlisted command comes back as an error, same as any other hosted client. This server has no tool for managing that allowlist itself; letting an agent widen its own restrictions through its own tool surface would defeat the point. It's an opt-in guardrail on top of pod isolation, not a sandbox-escape boundary — see the root README's The boxkite CLI ↗ section for why.

Whatever your BOXKITE_API_KEYcan reach is reachable by any MCP client wired to this server, unconditionally. Don't point it at an account whose sandboxes have broader privileges than you want an LLM agent to have unsupervised access to. Tool results are also unsanitized plain text — treat sandbox output as untrusted input flowing into the LLM's context, same as a web fetch.