boxxkite

Integration

MCP server

An MCP (Model Context Protocol) server over a control-plane — either boxxkite's own hosted cloud at api.boxxkite.com or your own self-hosted deployment, just by swapping BOXXKITE_BASE_URL below — 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 boxxkite-client
pip install boxxkite-mcp

Configure

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

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

Rather than editing a client's config file by hand, boxxkite 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 boxxkite 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
boxxkite mcp init claude-code
# Added the boxxkite MCP server entry in .mcp.json.
# Restart your MCP client to pick up the change.

Run

terminal
BOXXKITE_BASE_URL=https://api.boxxkite.com \
BOXXKITE_API_KEY=bxk_live_... \
boxxkite-mcp

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

Hosted MCP & OAuth

Instead of running a local stdio MCP subprocess on your machine, a boxxkite 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": {
    "boxxkite": {
      "url": "https://api.boxxkite.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 BOXXKITE_API_KEY in your shell, then:

~/.codex/config.toml
[mcp_servers.boxxkite]
url = "https://api.boxxkite.com/mcp"
bearer_token_env_var = "BOXXKITE_API_KEY"

If your deployment has MCP OAuth enabled (BOXXKITE_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 boxxkite 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 boxxkite CLI ↗ section for why.

Whatever your BOXXKITE_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.