Superserve Sandbox MCP

MCP 服务器

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

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

有两种运行方式：通过 npx 在 本地 通过标准输入输出运行，或者针对位于 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 密钥作为 持有者令牌 发送。该端点是无状态的，并且限定在账户范围内（您的密钥已映射到您的团队），每个沙箱的数据平面令牌永远不会离开服务器。

持有者身份验证适用于任何允许您设置请求头的客户端 — Claude Code、Cursor、VS Code 和 Anthropic Messages API 连接器。Claude.ai、 Claude Desktop 的自定义连接器 UI 和 ChatGPT 开发者模式不提供 静态持有者/自定义头字段（它们期望 OAuth），而托管端点目前不支持 OAuth — 在这些环境中请使用 [本地](#install) 安装。 ```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"
    }
  ]
}
```

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

工具

工具	功能
sandbox_create	创建一个新的沙箱；返回其 id。立即激活并准备就绪。接受 secrets 和出口规则。
sandbox_update	在创建后更改沙箱的元数据或出口（allow_out/deny_out）规则。
sandbox_list	列出您的沙箱（活跃和暂停），可按元数据筛选。
sandbox_info	获取一个沙箱的状态、资源、元数据、网络规则和密钥绑定。只读。
sandbox_exec	运行一个 shell 命令；返回标准输出、标准错误、退出代码。自动恢复暂停的沙箱。
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	恢复一个暂停的沙箱（通常不需要 — 执行操作会自动恢复）。
sandbox_kill	永久删除一个沙箱。
sandbox_preview_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_preview_url、sandbox_template_list、secret_list）已标注，以便客户端可以跳过确认提示；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 将标准输出和标准错误截断为各 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. 在创建时绑定 — 在 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 传递。

端口。 在沙箱中启动一个服务器（sandbox_exec，例如 python3 -m http.server 8000），然后调用 sandbox_preview_url 获取其公共 URL。任何绑定到端口的进程都可以在 https://{port}-{id}.sandbox.superserve.ai 上访问，无需身份验证 — 只公开您打算公开的端口。

尚未在 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 服务器封装的库。