Superserve Sandbox MCP

MCP 伺服器

從任何 MCP 用戶端建立、執行和管理 Superserve 沙箱。

想讓代理程式自行建立沙箱嗎？這個 MCP 伺服器可以做到。

Superserve MCP 伺服器（@superserve/mcp）將沙箱基礎元件公開為 Model Context Protocol 工具，因此任何支援 MCP 的用戶端——Claude、Cursor、VS Code、Windsurf、Codex——都可以在隔離的 Firecracker microVM 中建立沙箱、執行命令、讀寫檔案、建置範本、代理密鑰，以及控制網路存取。

有兩種執行方式：透過 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 的 Custom Connector 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. 在建立時綁定——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。

尚未納入 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 伺服器包裝的函式庫。