Superserve Sandbox MCP

MCP 伺服器

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

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 的託管端點使用 Streamable HTTP — 無需 npx，無需 Node。將您的 Superserve API 金鑰作為 承載權杖 傳送。端點是無狀態的，並且以帳戶為範圍（您的金鑰已對應到您的團隊），而每個沙箱的資料平面權杖永遠不會離開伺服器。

承載驗證適用於任何允許您設定請求標頭的客戶端 — Claude Code、Cursor、VS Code 和 Anthropic Messages API 連接器。Claude.ai、 Claude Desktop 的自訂連接器 UI 和 ChatGPT 開發者模式不提供 靜態承載 / 自訂標頭欄位（它們預期使用 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 命令；傳回 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（未經身份驗證 — 該連接埠上的任何內容都會暴露在網際網路上）。
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 將 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 傳遞。

連接埠。 在沙箱中啟動一個伺服器（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（stdin、訊號、長時間執行的處理程序）。
• 大型或串流傳輸 — 透過 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 伺服器所包裝的程式庫。