---
title: "MCP server"
description: "Connect Claude, Claude Code and other MCP clients to BoxCompute VMs."
---

> Documentation Index
> Fetch the complete documentation index at: https://boxcompute.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

BoxCompute's remote MCP server lets an AI app create Linux VMs in your account, run commands in
them, read and edit their files, and open preview URLs for servers they run.

```text
https://mcp.boxcompute.ai/mcp
```

You need a BoxCompute account with credit. New customers can
[join the early-access waitlist](https://boxcompute.ai/#waitlist).

## Connect an app

Apps that support MCP sign-in need only the URL. The first time the app connects, it opens a
BoxCompute page in your browser that names the app and what it will be able to do. Choose
**Allow access** to connect it, or **Cancel** to refuse.

### Claude

1. In Claude, open **Settings → Connectors**.
2. Choose **Add custom connector**, name it BoxCompute, and enter `https://mcp.boxcompute.ai/mcp`.
3. Choose **Connect** and sign in to BoxCompute when asked.

The connector is then available in Claude on the web, Claude Desktop and the Claude mobile apps.
### Claude Code

```sh
claude mcp add --transport http boxcompute https://mcp.boxcompute.ai/mcp
```

Then run `/mcp` in Claude Code, select **boxcompute** and choose **Authenticate**.
### Other clients

Add a remote (Streamable HTTP) server with the URL `https://mcp.boxcompute.ai/mcp`. A client that
supports MCP authorization signs you in through the browser. For one that does not, use an
[API key](#use-an-api-key-instead).

### What an app can do

The sign-in page lists what you grant:

| Permission | Tools |
| --- | --- |
| See your VMs and their files | `account_get`, `workspace_list`, `sandbox_list`, `sandbox_get`, `file_read`, `file_list` |
| Create, start and stop VMs | `sandbox_create`, `sandbox_start`, `sandbox_stop` |
| Run commands and change files in your VMs | `command_run`, `process_start`, `process_get`, `process_output`, `process_cancel`, `file_write`, `file_edit`, `preview_create` |
| Delete VMs and their disks | `sandbox_delete` |
| See your credit balance | the balance in `account_get` |

Allowing access creates an API key named after the app, such as **MCP · Claude**, on your
[API keys](https://app.boxcompute.ai/api-keys) page. The app acts as that key: its requests appear
in your [API activity](/audit-log/) and the VMs it creates are attributed to it. Revoke the key to
disconnect the app. Connecting again asks you to allow it again.

> **VM time is billed**
>
> VMs an app creates or starts are billed to your credit like any other VM. Reading a VM's state
> never starts it, but commands and file tools start a stopped VM so they can run. A VM stops 30
> minutes after the last command, process start, file or preview call and keeps its `/workspace`
> files; `sandbox_stop` stops it sooner.

## Use an API key instead

Every client can authenticate with a [BoxCompute API key](/api-keys/) in the `Authorization`
header. The key's scopes decide which tools the client is offered.

```sh
claude mcp add --transport http boxcompute https://mcp.boxcompute.ai/mcp \
  --header "Authorization: Bearer $BOXCOMPUTE_API_KEY"
```

For Cursor (`~/.cursor/mcp.json`) and similar clients:

```json
{
  "mcpServers": {
"boxcompute": {
  "url": "https://mcp.boxcompute.ai/mcp",
  "headers": { "Authorization": "Bearer ${env:BOXCOMPUTE_API_KEY}" }
}
  }
}
```

VS Code uses the same entry in `.vscode/mcp.json`, under `servers` instead of `mcpServers`.
Keep the key in an environment variable or secret store, not in a file you commit.

## Tools

| Tool | What it does |
| --- | --- |
| `account_get` | The account and key in use, and the credit balance when allowed |
| `workspace_list` | Workspaces in the account |
| `sandbox_list`, `sandbox_get` | VMs with their state, compute size, root-disk size when known, and network access |
| `sandbox_create` | Create and start a VM: small (0.5 vCPU, 1 GiB) or large (1.5 vCPU, 3 GiB), with or without internet; default 30 GiB root disk holding the OS and `/workspace` |
| `sandbox_start`, `sandbox_stop` | Start a stopped VM, or stop one now and keep its files |
| `sandbox_delete` | Permanently delete a VM and its `/workspace` |
| `command_run` | Run a shell command and wait up to 60 seconds |
| `process_start`, `process_get`, `process_output`, `process_cancel` | Run a command in the background for up to 15 minutes, check on it and read its output |
| `file_read`, `file_list` | Read a file or list a directory under `/workspace` |
| `file_write`, `file_edit` | Write a file (up to 2 MiB) or replace text in one |
| `preview_create` | A public HTTPS URL, valid for one hour, for a port a server in the VM listens on |

`sandbox_create` accepts optional `disk_gib`, a whole number from 10 to 30, defaulting to 30.
Below 30 requires early access; other accounts receive `INVALID_REQUEST`. The disk is fixed for
the VM's lifetime and counts in full against account storage even when stopped. `sandbox_list`
and `sandbox_get` return `disk_gib: null` for older VMs whose disk size was not recorded.
Do not infer those disks' sizes from today's default.

Each tool is marked read-only or not, and destructive or not, so your app can ask before it stops,
deletes or changes anything. These annotations describe the requested operation, not a guarantee
that compute stays stopped: `file_read` and `file_list` can start a stopped VM and incur compute
charges, even though they do not change its files. `sandbox_list` and `sandbox_get` never start it.

## Limits

- Every call answers within about 75 seconds. A VM that is still booting returns
  `ready: false` from `sandbox_create` or `sandbox_start`, and the boot continues; commands and
  file tools on it say it is still starting, and can be called again a few seconds later.
- Commands longer than 60 seconds belong in `process_start`.
- Files are confined to `/workspace`. `file_read` defaults to 64 KiB and allows up to 256 KiB
  per part; pass `next_offset` and the returned cursor to continue. Binary data is base64.
  `file_list` defaults to 200 entries and allows up to 500 per page; pass its cursor to continue.
- `command_run` output is capped at 48 KiB per stream. `process_start` retains up to 1 MiB
  per stream; `process_output` reads up to 48 KiB at a time. Pass `next_offset` back to continue;
  `earliest_offset` identifies output already discarded.
- A preview URL is public: anyone with it can reach that port until it expires.
- Account limits on running and total VMs apply as they do in the app and the
  [HTTP API](/limits-and-errors/).

Errors carry the same codes as the HTTP API, such as `INSUFFICIENT_CREDIT` or `NOT_FOUND`, with a
message the app can act on.

## Privacy and support

The app receives the output of the tools it calls, such as command output and file contents, and
handles it under its own terms. BoxCompute records each request in your API activity without the
tool's arguments. See the [privacy policy](https://boxcompute.ai/privacy/).

For help, email [support@boxcompute.ai](mailto:support@boxcompute.ai). Do not include API keys or
passwords in your message.

Source: https://boxcompute.ai/docs/mcp/index.mdx