Superserve Sandbox MCP

MCP 服务器

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

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

Superserve MCP 服务器（@superserve/mcp）将沙箱原语以模型上下文协议工具的形式暴露出来，因此任何支持 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 的托管端点支持流式 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_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（域名模式或 CIDR）添加允许的目标；deny_out（仅 CIDR）阻止它们。仅使用 allow_out 不会锁定沙箱——对于严格的允许列表，请将其与 deny_out: ["0.0.0.0/0"] 结合使用（先拒绝所有，然后允许列出的目标）。在 sandbox_create 或 sandbox_update 上设置这些，并使用 sandbox_network_log 审计沙箱实际访问的内容。
• 错误信息可操作。 失败的工具调用会返回一条简短消息，告诉智能体下一步该做什么——例如 "沙箱配额已满。请中止或删除一个沙箱，或稍后重试。"——而不是原始堆栈跟踪，因此智能体可以自我纠正。

密钥、模板和端口

密钥。 不要以明文 env_vars 传递凭据。请改为：

1. 使用 TypeScript SDK（Secret.create()）或控制台创建一次密钥——原始值永远不会通过智能体或 MCP 服务器传输，因此 密钥创建有意不作为 MCP 工具。
2. 使用 secret_list 发现可绑定的密钥（仅元数据——值永远不会离开平台）。
3. 在创建时绑定——secrets: { ANTHROPIC_API_KEY: "anthropic-prod" } 在 sandbox_create 上——或稍后使用 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。

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。 Bearer 令牌缺失或不是有效的 ss_live_ 密钥。请将其作为 Authorization: Bearer ss_live_… 发送（参见 托管）。

相关

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