Superserve Sandbox

@superserve/mcp

适用于 Superserve 沙箱的 Model Context Protocol 服务。可从任意 MCP 客户端（Claude、Cursor、VS Code、Windsurf、Codex）创建、运行命令并管理隔离的 Firecracker microVM。

通过 npx 在本地使用 stdio 运行。使用你的 Superserve API 密钥进行身份验证。每次调用都通过 ID 指定目标沙箱。

安装

将其添加到 MCP 客户端，并在其 env 中设置 SUPERSERVE_API_KEY（客户端不会从你的 shell 继承该变量）。在 console.superserve.ai 创建密钥。

Claude Code：

claude mcp add superserve \
  --env SUPERSERVE_API_KEY=ss_live_xxxxxxxxxxxxxxxx \
  -- npx -y @superserve/mcp

Claude Desktop / Cursor / Windsurf（claude_desktop_config.json、.cursor/mcp.json、mcp_config.json）：

{
  "mcpServers": {
    "superserve": {
      "command": "npx",
      "args": ["-y", "@superserve/mcp"],
      "env": { "SUPERSERVE_API_KEY": "ss_live_xxxxxxxxxxxxxxxx" }
    }
  }
}

VS Code（.vscode/mcp.json，会提示输入密钥）：

{
  "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}" }
    }
  }
}

Codex（~/.codex/config.toml）——env_vars 会从你的环境中转发密钥，而不是将其存储在文件中：

[mcp_servers.superserve]
command = "npx"
args = ["-y", "@superserve/mcp"]
env_vars = ["SUPERSERVE_API_KEY"]

托管（远程）

托管实例运行于 https://mcp.superserve.ai（Streamable HTTP），无需本地安装。将你的 Superserve API 密钥作为 bearer token 发送；该服务无状态，且作用域限定于账户（密钥已映射到你的团队）。

Bearer 身份验证适用于 Claude Code、Cursor、VS Code 和 Anthropic Messages API connector。Claude.ai、Claude Desktop 的 Custom Connector UI 和 ChatGPT developer mode 需要 OAuth（不支持静态 bearer 字段），而托管端点目前尚不支持 OAuth。

Claude Code：

claude mcp add --transport http superserve https://mcp.superserve.ai \
  --header "Authorization: Bearer ss_live_xxxxxxxxxxxxxxxx"

Cursor / VS Code（.cursor/mcp.json、.vscode/mcp.json）：

{
  "servers": {
    "superserve": {
      "type": "http",
      "url": "https://mcp.superserve.ai",
      "headers": { "Authorization": "Bearer ss_live_xxxxxxxxxxxxxxxx" }
    }
  }
}

运行托管服务

同一个包也包含托管服务。可独立运行（自托管 / staging）：

PORT=8080 SUPERSERVE_BASE_URL=https://api.superserve.ai \
  npx -y -p @superserve/mcp superserve-mcp-http

也可以在任意 fetch 运行时中挂载符合 Web 标准的处理器（例如 Next.js 路由处理器）：

import { handleMcpRequest } from "@superserve/mcp/http"

export const POST = (req: Request) => handleMcpRequest(req)

它在 /（POST）提供 MCP 端点，并提供 GET /health 存活探测。配置项：PORT（默认值为 8080）、SUPERSERVE_BASE_URL（可选）。API 密钥会在每次请求时从 bearer 标头中读取，且绝不会记录到日志中。

工具

工具	描述
sandbox_create	创建沙箱；返回其 id。接受 secrets 绑定和出站规则。
sandbox_update	创建后更改沙箱元数据或出站（allow_out/deny_out）规则。
sandbox_list	列出沙箱（运行中和已暂停），可按元数据筛选。
sandbox_info	获取沙箱的状态、资源、元数据、网络规则和密钥绑定。
sandbox_exec	运行 Shell 命令；返回标准输出、标准错误和退出代码。自动恢复已暂停的沙箱。
sandbox_computer	操控图形界面桌面沙箱：截图、鼠标、键盘、滚动、调整大小、实时查看器 URL。输入操作会返回一张新的截图（JPEG）。
sandbox_files_read	读取文件（UTF-8 文本或 base64）。拒绝超过 1 MiB 的文件。
sandbox_files_write	创建或覆盖文件（内联内容上限为 8 MiB）。
sandbox_files_list	列出目录内容。
sandbox_files_download_dir	将目录下载为 base64 ZIP（跳过符号链接）。上限为 10 MiB。
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_create、sandbox_list、sandbox_template_list、sandbox_template_create 和 secret_list 外，所有工具都需要 sandbox_id。有意不开放密钥的_创建_操作（原始值应保留在 SDK/控制台中，而不应出现在 Agent 对话记录中）；服务端只绑定现有密钥。

配置

变量	必需	默认值
SUPERSERVE_API_KEY	是	—
SUPERSERVE_BASE_URL	否	https://api.superserve.ai

开发

bun install
bunx turbo run build     --filter=@superserve/mcp
bunx turbo run typecheck --filter=@superserve/mcp
bunx turbo run test      --filter=@superserve/mcp        # unit + in-memory integration (no credentials)
SUPERSERVE_API_KEY=ss_live_... bunx turbo run e2e --filter=@superserve/mcp   # live round-trip

该服务是 @superserve/sdk 的轻量适配器；SDK 管理每个沙箱的数据平面访问令牌，不会将其暴露给模型。

许可证

Apache-2.0