Superserve Sandbox MCP

MCP 服务器

从任何 MCP 客户端创建、运行和管理 Superserve 沙箱。

想要让代理自己创建沙箱？这个 MCP 服务器就能做到。

Superserve MCP 服务器（@superserve/mcp）将沙箱原语暴露为 Model Context Protocol 工具，因此任何支持 MCP 的客户端——Claude、Cursor、VS Code、Windsurf、Codex——都可以在隔离的 Firecracker 微虚拟机中创建沙箱、运行命令、读写文件、构建模板、管理密钥代理以及控制网络访问。

有两种运行方式：通过 npx 在 本地 通过 stdio 运行，或者通过 https://mcp.superserve.ai 的 托管 端点运行，无需本地安装。两者都使用你的 SUPERSERVE_API_KEY 进行身份验证，并按 ID 定位每次调用的沙箱。它是 TypeScript SDK 的轻量封装，因此每个沙箱的数据平面令牌永远不会到达模型。

快速开始

将服务器添加到你的客户端（参见 安装），然后让代理 "创建一个沙箱并在其中运行 python --version。" 代理会调用 sandbox_create，然后调用 sandbox_exec，并报告结果——无需你编写任何代码。

你需要一个 Superserve API 密钥——在 API 密钥 页面创建一个。无需全局安装；npx 会在首次使用时获取服务器。

安装

注意

在服务器的 env 中设置 SUPERSERVE_API_KEY——MCP 客户端不会从你的 shell 继承它。如果你的客户端支持，优先使用密钥输入提示，而不是粘贴原始密钥（参见下面的 VS Code）。

```bash theme={"theme":{"light":"github-light","dark":"vitesse-dark"}} claude mcp add superserve \ --env SUPERSERVE_API_KEY=ss_live_xxxxxxxxxxxxxxxx \ -- npx -y @superserve/mcp ``` 添加到 `claude_desktop_config.json`（macOS：`~/Library/Application Support/Claude/`）：

```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "mcpServers": {
    "superserve": {
      "command": "npx",
      "args": ["-y", "@superserve/mcp"],
      "env": { "SUPERSERVE_API_KEY": "ss_live_xxxxxxxxxxxxxxxx" }
    }
  }
}
```

添加到 `.cursor/mcp.json`（项目）或 `~/.cursor/mcp.json`（全局）：

```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "mcpServers": {
    "superserve": {
      "command": "npx",
      "args": ["-y", "@superserve/mcp"],
      "env": { "SUPERSERVE_API_KEY": "ss_live_xxxxxxxxxxxxxxxx" }
    }
  }
}
```

添加到 `.vscode/mcp.json`。`inputs` 块会提示输入密钥，而不是以纯文本存储：

```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "inputs": [
    {
      "id": "superserve-key",
      "type": "promptString",
      "description": "Superserve API key",
      "password": true
    }
  ],
  "servers": {
    "superserve": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@superserve/mcp"],
      "env": { "SUPERSERVE_API_KEY": "${input:superserve-key}" }
    }
  }
}
```

添加到 `~/.codeium/windsurf/mcp_config.json`：

```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "mcpServers": {
    "superserve": {
      "command": "npx",
      "args": ["-y", "@superserve/mcp"],
      "env": { "SUPERSERVE_API_KEY": "ss_live_xxxxxxxxxxxxxxxx" }
    }
  }
}
```

添加到 `~/.codex/config.toml`。`env_vars` 会从你的环境转发 `SUPERSERVE_API_KEY`，因此原始密钥不会存储在配置文件中（先在 shell 中导出）。Codex 还会读取服务器的 `instructions` 以获取跨工具工作流指导。

```toml theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
[mcp_servers.superserve]
command = "npx"
args = ["-y", "@superserve/mcp"]
env_vars = ["SUPERSERVE_API_KEY"]
```

对于 [托管](#hosted-remote) 端点，使用 `url = "https://mcp.superserve.ai"` 和 `bearer_token_env_var = "SUPERSERVE_API_KEY"`。

托管（远程）

不想在本地运行任何东西？位于 https://mcp.superserve.ai 的托管端点支持 Streamable HTTP——无需 npx，无需 Node。将你的 Superserve API 密钥作为 Bearer 令牌 发送。该端点是无状态的且按账户范围（你的密钥已映射到你的团队），并且每个沙箱的数据平面令牌永远不会离开服务器。

注意

Bearer 认证适用于任何允许你设置请求头的客户端——Claude Code、Cursor、VS Code 和 Anthropic Messages API 连接器。Claude.ai、Claude Desktop 的自定义连接器 UI 和 ChatGPT 开发者模式不提供静态 Bearer / 自定义头字段（它们期望 OAuth），而托管端点尚不支持 OAuth——请在这些地方使用 本地 安装。

```bash theme={"theme":{"light":"github-light","dark":"vitesse-dark"}} claude mcp add --transport http superserve https://mcp.superserve.ai \ --header "Authorization: Bearer ss_live_xxxxxxxxxxxxxxxx" ``` 添加到 `.cursor/mcp.json`（项目）或 `~/.cursor/mcp.json`（全局）：

```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "mcpServers": {
    "superserve": {
      "url": "https://mcp.superserve.ai",
      "headers": { "Authorization": "Bearer ss_live_xxxxxxxxxxxxxxxx" }
    }
  }
}
```

添加到 `.vscode/mcp.json`。`inputs` 块会提示输入密钥，而不是以纯文本存储：

```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "inputs": [
    {
      "id": "superserve-key",
      "type": "promptString",
      "description": "Superserve API key",
      "password": true
    }
  ],
  "servers": {
    "superserve": {
      "type": "http",
      "url": "https://mcp.superserve.ai",
      "headers": { "Authorization": "Bearer ${input:superserve-key}" }
    }
  }
}
```

在 [Anthropic Messages API](https://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector) 请求中作为连接器传递：

```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "mcp_servers": [
    {
      "type": "url",
      "name": "superserve",
      "url": "https://mcp.superserve.ai",
      "authorization_token": "ss_live_xxxxxxxxxxxxxxxx"
    }
  ]
}
```

与本地服务器具有相同的工具和行为——唯一的区别是传输方式，以及密钥作为 Bearer 头而不是 env 变量传输。

工具

工具	功能
sandbox_create	创建新沙箱；返回其 id。接受 secrets、出站规则和 preview_access。
sandbox_update	更改元数据、出站规则、生命周期窗口或 preview_access。
sandbox_list	列出你的沙箱（活动和中止的），可按元数据过滤。
sandbox_info	获取一个沙箱的状态、资源、元数据、网络规则和密钥绑定。只读。
sandbox_exec	运行 shell 命令；返回 stdout、stderr、退出代码。自动恢复已中止的沙箱。
sandbox_files_read	读取文件（UTF-8 文本，或二进制文件的 base64）。
sandbox_files_write	创建或覆盖文件。父目录会自动创建。
sandbox_files_list	列出目录条目（名称、类型、大小、修改时间）。
sandbox_files_download_dir	将目录下载为 base64 ZIP（跳过符号链接）。上限为 10 MiB；更大的 → 使用 SDK/CLI。
sandbox_pause	中止沙箱；状态会被保留。
sandbox_resume	恢复已中止的沙箱（通常不需要——exec 会自动恢复）。
sandbox_kill	永久删除沙箱。
sandbox_preview_url	发布端口并返回一个干净的公共 URL 或一个过期的私有签名 URL。
sandbox_network_log	审计沙箱的出站连接（主机、判定、字节数），无需恢复它。
sandbox_computer	驱动 GUI 桌面沙箱：截图、鼠标、键盘、滚动、调整大小、查看器 URL。每次调用一个操作。
sandbox_template_list	列出你的团队可以启动的模板（基础镜像）。
sandbox_template_create	使用特定的 vCPU/内存/磁盘配置或预装软件构建自定义模板（异步——轮询直到就绪）。
secret_list	列出可绑定的团队密钥（仅元数据——绝不包含值）。
sandbox_attach_secret	将存储的密钥绑定到运行中的沙箱，作为环境变量。
sandbox_detach_secret	从沙箱中移除密钥绑定。

大多数工具接受 sandbox_id；例外是 sandbox_create、sandbox_list、sandbox_template_list、sandbox_template_create 和 secret_list。从这些工具之一开始获取 ID，然后将其传递给后续调用。只读工具（sandbox_list、sandbox_info、sandbox_files_read、sandbox_files_list、sandbox_files_download_dir、sandbox_network_log、sandbox_template_list、secret_list）已标注，以便客户端跳过确认提示；sandbox_preview_url 是幂等写入，因为它发布请求的端口，而 sandbox_kill 被标注为破坏性操作。

示例

一个典型的代理流程，用于 "启动一个沙箱，编写一个打印前几个质数的 Python 脚本并运行它"：

sandbox_create       { name: "primes" }
                       → { id: "a1b2c3…", name: "primes", status: "active" }

sandbox_files_write  { sandbox_id: "a1b2c3…", path: "/app/primes.py", content: "…" }
                       → { path: "/app/primes.py", bytes: 142 }

sandbox_exec         { sandbox_id: "a1b2c3…", command: "python /app/primes.py" }
                       → { exit_code: 0, stdout: "2 3 5 7 11 13 17 19 23 29", stderr: "" }

完成后，代理可以 sandbox_pause（状态保留，保留更便宜）或 sandbox_kill（永久删除）。

配置

变量	必需	描述
SUPERSERVE_API_KEY	是	你的 Superserve API 密钥（以 ss_live_ 开头）。
SUPERSERVE_BASE_URL	否	覆盖控制平面 URL（默认为 https://api.superserve.ai）。

行为和限制

• 自动恢复。 sandbox_exec 和文件工具会透明地恢复已中止的沙箱，因此代理永远不需要先调用 sandbox_resume。sandbox_resume 仅用于显式预热沙箱。
• 输出有上限以保护上下文。 sandbox_exec 将 stdout 和 stderr 截断为每个 32 KiB——截断的结果会设置 truncated: true 并报告原始字节长度。sandbox_files_read 拒绝 大于 1 MiB 的文件（不返回部分内容）；错误会告诉你使用 sandbox_exec 读取切片（例如 head -c）或使用 SDK/CLI 下载整个文件。sandbox_files_write 的内联内容上限为 8 MiB。
• 默认命令超时为 60 秒，上限为 10 分钟。每次调用可使用 timeout_ms 覆盖。
• 出站流量可控。 allow_out（域名模式、IP 或 CIDR）添加允许的目标；deny_out（IP 或 CIDR，不支持域名）阻止它们。仅使用 allow_out 不会 锁定沙箱——对于严格的允许列表，将其与 deny_out: ["0.0.0.0/0"] 结合使用（拒绝所有，然后允许列出的目标）。如果允许列表有域名规则或工作负载解析主机名，还要允许沙箱的 DNS 解析器 1.1.1.1/32 和 8.8.8.8/32，因为拒绝所有也会阻止 DNS；在仅 IP 的允许列表中省略它们，因为允许的解析器只是额外的出站通道。在 sandbox_create 或 sandbox_update 上设置这些，并使用 sandbox_network_log 审计沙箱实际访问的内容。
• 错误信息可操作。 失败的工具调用会返回一条简短消息，告诉代理下一步该做什么——例如 "沙箱配额已用尽。请中止或删除一个沙箱，或稍后重试。"——而不是原始堆栈跟踪，以便代理可以自我纠正。

密钥、模板和端口

密钥。 不要将凭据作为明文 env_vars 传递。而是：

1. 使用 TypeScript SDK（Secret.create()）或 控制台 创建一次密钥——原始值永远不会经过代理或 MCP 服务器，因此 密钥创建故意不是 MCP 工具。
2. 使用 secret_list 发现可绑定的密钥（仅元数据——值永远不会离开平台）。
3. 在创建时绑定——sandbox_create 上的 secrets: { ANTHROPIC_API_KEY: "anthropic-prod" }——或稍后使用 sandbox_attach_secret / sandbox_detach_secret。

沙箱会看到一个代理令牌；平台仅在向密钥允许的主机发出出站请求时交换真实凭据。

模板。 沙箱从其模板继承 vCPU/内存/磁盘，并且无法在 sandbox_create 时覆盖。要获得特定的配置（例如 4 vCPU 沙箱）或预装软件，请使用 sandbox_template_create 构建模板，然后轮询 sandbox_template_list 直到其 status 为 ready，再将其作为 from_template 传递。

端口。 新的 MCP 沙箱使用 public 作为新发布端口的默认访问方式；只有显式发布的端口才可访问。传递 preview_access: "private" 给 sandbox_create（或 sandbox_update）以更改未来端口的默认值。现有端口保留其自身模式。使用 sandbox_exec 启动服务器，然后调用 sandbox_preview_url；该工具会幂等地发布该端口，并使用返回的端口模式返回干净的公共 URL 或过期的私有签名 URL。私有链接默认为一小时；将 expires_in_seconds 设置为 1 到 604800 秒之间的值。参见 预览 URL。

计算机使用

sandbox_computer 驱动从桌面模板（如 superserve/desktop）创建的沙箱中的 GUI 桌面。每次调用接受一个 action，使用计算机使用模型输出的词汇：screenshot、left_click、right_click、middle_click、double_click、triple_click、left_click_drag、left_mouse_down、left_mouse_up、mouse_move、key、type、scroll、wait、resize 和 stream_url。指针操作接受屏幕像素中的 coordinate: [x, y]（原点在左上角）；key 和 type 接受 text；scroll 接受 scroll_direction 和可选的 scroll_amount。

sandbox_create    { name: "browser", from_template: "superserve/desktop" }
sandbox_computer  { sandbox_id: "a1b2c3…", action: "left_click", coordinate: [640, 32] }
                    → text "left_click done (1280x800)" + image/png
sandbox_computer  { sandbox_id: "a1b2c3…", action: "type", text: "https://example.com" }
sandbox_computer  { sandbox_id: "a1b2c3…", action: "key", text: "Return" }

输入操作会返回结果的新截图，因此模型的行动-然后-观察回合只需一次工具调用；连续发送多个操作时传递 screenshot_after: false。wait 会暂停 duration_ms（上限为 10 秒），无需向沙箱发出请求。stream_url 在沙箱的预览策略下返回桌面的实时浏览器查看器。

如果输入操作失败，输入可能已经传递。工具会说明这一点，并要求代理在重复操作前先截图。参见 桌面指南 了解底层 SDK 接口。

尚未在 MCP 接口中

MCP 服务器覆盖了常见的智能体循环；上表是完整的 v1 工具集。部分 SDK 功能尚未开放——如需使用，请直接查阅 TypeScript SDK：

• 密钥创建 — Secret.create()（MCP 服务器仅绑定现有密钥）。
• 流式与交互式命令 — 流式 run() 回调和 commands.spawn（标准输入、信号、长时间运行的进程）。
• 大型或流式传输 — 目录下载通过 sandbox_files_download_dir 支持最高 10 MiB；超出该限制（以及归档/流式上传或超过 1 MiB 读取 / 8 MiB 内联写入上限的单个文件），请使用 SDK/CLI（files.downloadDir，流式上传）。
• 计费与提供商发现 — 使用数据和 Provider.list() 用于密钥提供商设置。

这些已作为后续事项跟踪。

工作原理

服务器封装了 TypeScript SDK，并且仅持有你的控制平面 SUPERSERVE_API_KEY。每次工具调用都会按 ID 连接到目标沙箱；SDK 在内部管理每个沙箱的数据平面访问令牌，并在恢复时轮换它，因此它永远不会暴露给模型或出现在工具输出中。工具是无状态的——没有隐藏的“当前沙箱”——这保证了多轮和并行工具调用中的行为可预测。

故障排查

• 工具不出现，或服务器无法启动。 API 密钥几乎总是原因——MCP 客户端不会继承你 shell 中的环境变量。请在服务器的 env 块中设置 SUPERSERVE_API_KEY（参见 安装），而不仅仅是在终端中设置。
• Authentication failed。 密钥缺失或无效。生产密钥以 ss_live_ 开头；请在 API 密钥 页面创建一个。
• 首次调用较慢。 npx 在首次使用时下载包并缓存；后续启动会很快。
• 需要 Node 18+。 本地服务器通过 npx 在 Node 上运行。（托管 端点没有本地运行时要求。）
• 来自托管端点的 401 Unauthorized。 持有者令牌缺失或不是有效的 ss_live_ 密钥。请将其作为 Authorization: Bearer ss_live_… 发送（参见 托管）。

相关

暂停、恢复和删除沙箱。 执行、流式、工作目录、环境变量和超时。 代理提供商密钥，而不将其暴露给沙箱。 MCP 服务器所封装的库。

本文档基于 Mintlify 构建和托管，这是一个开发者文档平台。