Superserve Sandbox MCP

官方

由 Superserve 託管的代理安全虛擬機器

造訪 superserve.ai

你可以用 Superserve Sandbox MCP 做什麼？

建立並執行沙箱 — 請您的助理啟動沙箱並執行如 python --version 的指令，使用 sandbox_create 和 sandbox_exec。
管理沙箱中的檔案 — 請您的助理使用 sandbox_files_read、sandbox_files_write 和 sandbox_files_list 在沙箱內讀取、寫入或列出檔案。
控制網路存取 — 在 sandbox_create 或 sandbox_update 上設定出口規則，以允許或封鎖對外目的地，然後使用 sandbox_network_log 稽核流量。
發布預覽 URL — 請您的助理呼叫 sandbox_preview_url 來公開執行中的服務，以取得公開或限時有效的私人連結。
驅動 GUI 桌面 — 使用 sandbox_computer 在桌面沙箱中進行螢幕截圖、點擊、輸入或捲動，以執行瀏覽器自動化任務。
管理沙箱生命週期 — 使用 sandbox_pause、sandbox_resume 和 sandbox_kill 暫停、恢復或永久刪除沙箱。

文件

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 的自訂連接器 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_computer`	驅動 GUI 桌面沙箱：螢幕截圖、滑鼠、鍵盤、捲動、調整大小、檢視器 URL。每次呼叫一個動作。
`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（網域模式、IP 或 CIDR）新增允許的目的地；deny_out（IP 或 CIDR，不含網域）封鎖它們。僅使用 allow_out 不會鎖定沙箱——若要嚴格的允許清單，請將其與 deny_out: ["0.0.0.0/0"] 結合（拒絕全部，然後允許列出的目的地）。如果允許清單有網域規則或工作負載會解析主機名稱，也請允許沙箱的 DNS 解析器 1.1.1.1/32 和 8.8.8.8/32，因為拒絕全部也會封鎖 DNS；在僅 IP 的允許清單中請將它們排除，因為允許的解析器只是額外的對外通道。在 sandbox_create 或 sandbox_update 上設定這些，並使用 sandbox_network_log 稽核沙箱實際連線的內容。
錯誤訊息可操作。 失敗的工具呼叫會傳回簡短訊息，告訴代理程式下一步該做什麼——例如 「已達沙箱配額。請暫停或終止一個沙箱，或稍後重試。」——而非原始堆疊追蹤，因此代理程式可以自行修正。

機密、範本與連接埠

機密。 不要以純文字 env_vars 傳遞憑證。請改為：

使用 TypeScript SDK（Secret.create()）或主控台建立一次機密——原始值永遠不會經過代理程式或 MCP 伺服器，因此 機密建立刻意不是 MCP 工具。
使用 secret_list 探索可繫結的機密（僅中繼資料——值永遠不會離開平台）。
在建立時繫結——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。

電腦使用

sandbox_computer 驅動從桌面範本（例如 superserve/desktop）建立的沙箱中的 GUI 桌面。每次呼叫接受一個 action，使用電腦使用模型輸出的詞彙：screenshot、left_click、right_click、middle_click、double_click、triple_click、left_click_drag、left_mouse_down、left_mouse_up、mouse_move、key、type、scroll、wait、resize 及 stream_url。指標動作接受以螢幕像素為單位的 coordinate: [x, y]（原點在左上角）；key 和 type 接受 text；scroll 接受 scroll_direction 及選用的 scroll_amount。

sandbox_create    { name: "browser", from_template: "superserve/desktop" }
sandbox_computer  { sandbox_id: "a1b2c3…", action: "left_click", coordinate: [640, 32] }
                    → text "left_click done (1280x800)" + image/png
sandbox_computer  { sandbox_id: "a1b2c3…", action: "type", text: "https://example.com" }
sandbox_computer  { sandbox_id: "a1b2c3…", action: "key", text: "Return" }

輸入動作會傳回結果的新螢幕截圖，因此模型的動作後檢視回合只需一次工具呼叫；連續傳送多個動作時請傳遞 screenshot_after: false。wait 會暫停 duration_ms（上限為 10 秒），無需向沙箱發出請求。stream_url 在沙箱的預覽政策下傳回桌面的即時瀏覽器檢視器。

如果輸入動作失敗，輸入可能已送達。工具會如此說明，並要求代理程式在重複動作前先截圖。請參閱桌面指南以了解底層 SDK 介面。

尚未納入 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_… 傳送（請參閱託管）。