Superserve Sandbox MCP

ทางการ

เครื่องเสมือนที่ปลอดภัยสำหรับเอเจนต์ที่โฮสต์โดย Superserve

ดูบน superserve.aiลองใช้ MCP นี้ผู้สนับสนุน

คุณทำอะไรได้บ้างด้วย Superserve Sandbox MCP?

  • สร้างและรันแซนด์บ็อกซ์ — ขอให้ผู้ช่วยของคุณสร้างแซนด์บ็อกซ์ด้วย sandbox_create และรันคำสั่งเช่น python --version ผ่าน sandbox_exec
  • จัดการไฟล์ในแซนด์บ็อกซ์ — ใช้ sandbox_files_write, sandbox_files_read, และ sandbox_files_list เพื่อสร้าง ดู หรือจัดระเบียบไฟล์ภายในแซนด์บ็อกซ์
  • ควบคุมวงจรชีวิตของแซนด์บ็อกซ์ — หยุดชั่วคราว ดำเนินการต่อ หรือลบแซนด์บ็อกซ์อย่างถาวรด้วย sandbox_pause, sandbox_resume, และ sandbox_kill เพื่อจัดการทรัพยากร
  • เผยแพร่ URL ตัวอย่าง — เปิดเผยบริการที่กำลังทำงานโดยเรียก sandbox_preview_url เพื่อรับลิงก์สาธารณะหรือลิงก์ส่วนตัวที่หมดอายุได้
  • ผูกความลับอย่างปลอดภัย — แนบหรือถอดความลับของทีมที่เก็บไว้กับแซนด์บ็อกซ์ผ่าน sandbox_attach_secret และ sandbox_detach_secret โดยไม่เปิดเผยค่าดิบ
  • สร้างเทมเพลตที่กำหนดเอง — สร้างเทมเพลตแซนด์บ็อกซ์ที่นำกลับมาใช้ใหม่ได้ด้วยรูปแบบ CPU/หน่วยความจำ/ดิสก์เฉพาะโดยใช้ sandbox_template_create และแสดงรายการด้วย sandbox_template_list

เอกสาร

MCP Server

สร้าง รัน และจัดการ Superserve sandboxes จาก MCP client ใดก็ได้

ต้องการให้ agent สร้าง sandboxes ด้วยตัวเองหรือไม่? MCP server นี้ทำได้

MCP server ของ Superserve (@superserve/mcp) เปิดเผย sandbox primitives เป็นเครื่องมือ Model Context Protocol ดังนั้น client ที่รองรับ MCP ใดก็ได้ — Claude, Cursor, VS Code, Windsurf, Codex — สามารถสร้าง sandboxes, รันคำสั่ง, อ่านและเขียนไฟล์, สร้าง templates, จัดการ secrets, และควบคุมการเข้าถึงเครือข่ายใน Firecracker microVM ที่แยกออกมา

รันได้สองวิธี: ในเครื่อง ผ่าน stdio ด้วย npx หรือกับ hosted endpoint ที่ https://mcp.superserve.ai โดยไม่ต้องติดตั้งในเครื่อง ทั้งสองวิธีตรวจสอบสิทธิ์ด้วย SUPERSERVE_API_KEY ของคุณและกำหนดเป้าหมาย sandbox ต่อการเรียกตาม ID มันเป็น wrapper บางๆ เหนือ TypeScript SDK ดังนั้น per-sandbox data-plane token จะไม่ไปถึงโมเดล

Quickstart

เพิ่ม server ไปยัง client ของคุณ (ดู Install) จากนั้นขอให้ agent "สร้าง sandbox และรัน python --version ในนั้น" agent จะเรียก sandbox_create จากนั้น sandbox_exec และรายงานผลลัพธ์ — โดยไม่ต้องเขียนโค้ดจากคุณ

คุณต้องมี Superserve API key — สร้างได้ที่หน้า API key ไม่มีการติดตั้งแบบ global; npx จะดึง server มาในการใช้งานครั้งแรก

Install

Note

ตั้งค่า SUPERSERVE_API_KEY ใน env ของ server — MCP clients ไม่ได้รับค่าต่อจาก shell ของคุณ ควรใช้ secret-input prompt มากกว่าการวาง key ดิบในที่ที่ client ของคุณรองรับ (ดู 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` (global): 
```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` จะถามหา key แทนการเก็บเป็น plain text: 
```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` จาก environment ของคุณ ดังนั้น key ดิบจะไม่ถูกเก็บในไฟล์ config (export ใน shell ก่อน) Codex ยังอ่าน `instructions` ของ server สำหรับคำแนะนำ workflow ข้ามเครื่องมือ 
```toml theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
[mcp_servers.superserve]
command = "npx"
args = ["-y", "@superserve/mcp"]
env_vars = ["SUPERSERVE_API_KEY"]
```

สำหรับ [hosted](#hosted-remote) endpoint ใช้ `url = "https://mcp.superserve.ai"` กับ `bearer_token_env_var = "SUPERSERVE_API_KEY"`

Hosted (remote)

ไม่อยากรันอะไรในเครื่อง? hosted endpoint ที่ https://mcp.superserve.ai พูด Streamable HTTP — ไม่ต้องใช้ npx ไม่ต้องใช้ Node ส่ง Superserve API key ของคุณเป็น bearer token endpoint ไม่มีสถานะและจำกัดตามบัญชี (key ของคุณแมปกับทีมของคุณแล้ว) และ per-sandbox data-plane token ไม่เคยออกจาก server

Note

Bearer auth ทำงานใน client ใดก็ได้ที่ให้คุณตั้งค่า request header — Claude Code, Cursor, VS Code, และ Anthropic Messages API connector Claude.ai, Claude Desktop's Custom Connector UI, และ ChatGPT developer mode ไม่มีฟิลด์ static-bearer / custom-header (พวกเขาคาดหวัง OAuth) ซึ่ง hosted endpoint ยังไม่รองรับ — ใช้ local 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` (global): 
```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` จะถามหา key แทนการเก็บเป็น plain text: 
```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}" }
    }
  }
}
```
ส่งเป็น connector ในคำขอ [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"
    }
  ]
}
```

เครื่องมือและพฤติกรรมเหมือนกับ local server — ข้อแตกต่างคือ transport และ key ที่เดินทางเป็น bearer header แทนตัวแปร env

Tools

Toolสิ่งที่ทำ
sandbox_createสร้าง sandbox ใหม่; คืนค่า id ยอมรับ secrets, กฎ egress, และ preview_access
sandbox_updateเปลี่ยน metadata, กฎ egress, ช่วงเวลา lifecycle, หรือ preview_access
sandbox_listแสดงรายการ sandboxes ของคุณ (active และ paused), กรองตาม metadata
sandbox_infoดูสถานะ ทรัพยากร metadata กฎเครือข่าย และ secret bindings ของ sandbox หนึ่ง อ่านอย่างเดียว
sandbox_execรันคำสั่ง shell; คืนค่า stdout, stderr, exit code resume sandbox ที่ paused อัตโนมัติ
sandbox_files_readอ่านไฟล์ (UTF-8 text หรือ base64 สำหรับ binary)
sandbox_files_writeสร้างหรือเขียนทับไฟล์ สร้างไดเรกทอรีแม่โดยอัตโนมัติ
sandbox_files_listแสดงรายการในไดเรกทอรี (ชื่อ, ประเภท, ขนาด, เวลาแก้ไข)
sandbox_files_download_dirดาวน์โหลดไดเรกทอรีเป็น base64 ZIP (ข้าม symlinks) จำกัดที่ 10 MiB; ใหญ่กว่านั้น → ใช้ SDK/CLI
sandbox_pauseหยุด sandbox ชั่วคราว; สถานะถูกเก็บรักษา
sandbox_resumeresume sandbox ที่ paused (ปกติไม่จำเป็น — exec resume อัตโนมัติ)
sandbox_killลบ sandbox ถาวร
sandbox_preview_urlเผยแพร่พอร์ตและคืนค่า public URL ที่สะอาดหรือ private signed URL ที่หมดอายุ
sandbox_network_logตรวจสอบการเชื่อมต่อขาออกของ sandbox (host, verdict, bytes) โดยไม่ต้อง resume
sandbox_template_listแสดงรายการ templates (base images) ที่ทีมของคุณสามารถใช้เริ่มต้นได้
sandbox_template_createสร้าง template ที่กำหนดเองด้วยรูปร่าง vCPU/หน่วยความจำ/ดิสก์เฉพาะหรือซอฟต์แวร์ที่ติดตั้งไว้ล่วงหน้า (async — poll จนพร้อม)
secret_listแสดงรายการ team secrets ที่ผูกได้ (metadata เท่านั้น — ไม่มีค่า)
sandbox_attach_secretผูก secret ที่เก็บไว้กับ sandbox ที่รันอยู่ภายใต้ env var
sandbox_detach_secretเอา secret binding ออกจาก sandbox

เครื่องมือส่วนใหญ่รับ 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) ถูก annotate เพื่อให้ clients ข้ามขั้นตอนยืนยันได้; sandbox_preview_url เป็น idempotent write เพราะเผยแพร่พอร์ตที่ขอ และ sandbox_kill ถูก annotate ว่า destructive

Example

โฟลว์ agent ทั่วไปสำหรับ "สร้าง sandbox เขียน Python script ที่พิมพ์ primes แรก และรันมัน":

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

เมื่อเสร็จแล้ว agent สามารถ sandbox_pause (สถานะถูกเก็บ ถูกกว่าในการเก็บไว้) หรือ sandbox_kill (ถาวร)

Configuration

Variableจำเป็นคำอธิบาย
SUPERSERVE_API_KEYใช่Superserve API key ของคุณ (ขึ้นต้นด้วย ss_live_)
SUPERSERVE_BASE_URLไม่แทนที่ control-plane URL (ค่าเริ่มต้นคือ https://api.superserve.ai)

Behavior and limits

  • Auto-resume. sandbox_exec และเครื่องมือไฟล์ resume sandbox ที่ paused อย่างโปร่งใส ดังนั้น agents ไม่ต้องเรียก sandbox_resume ก่อน sandbox_resume มีไว้เพื่อ warm sandbox อย่างชัดเจนเท่านั้น
  • Output ถูกจำกัดสำหรับ context. sandbox_exec ตัด stdout และ stderr ที่ 32 KiB ต่ออัน — ผลลัพธ์ที่ถูกตัดจะตั้งค่า truncated: true และรายงานความยาวไบต์เดิม sandbox_files_read ปฏิเสธ ไฟล์ที่ใหญ่กว่า 1 MiB (ไม่คืนค่าเนื้อหาบางส่วน); ข้อผิดพลาดจะบอกให้อ่านเป็นชิ้นด้วย sandbox_exec (เช่น head -c) หรือดาวน์โหลดทั้งไฟล์ด้วย SDK/CLI sandbox_files_write inline content จำกัดที่ 8 MiB
  • ค่าเริ่มต้น command timeout คือ 60 วินาที สูงสุด 10 นาที แทนที่ต่อการเรียกด้วย timeout_ms
  • Egress ควบคุมได้ allow_out (รูปแบบโดเมนหรือ CIDRs) เพิ่มปลายทางที่อนุญาต; deny_out (CIDRs เท่านั้น) บล็อกพวกมัน allow_out เพียงอย่างเดียว ไม่ ล็อก sandbox ลง — สำหรับ allowlist ที่เข้มงวด รวมกับ deny_out: ["0.0.0.0/0"] (ปฏิเสธทั้งหมด แล้วอนุญาตปลายทางที่ระบุ) ตั้งค่าเหล่านี้บน sandbox_create หรือ sandbox_update และตรวจสอบสิ่งที่ sandbox เข้าถึงจริงด้วย sandbox_network_log
  • ข้อผิดพลาดนำไปปฏิบัติได้ การเรียกเครื่องมือที่ล้มเหลวคืนค่าข้อความสั้นๆ บอก agent ว่าต้องทำอะไรต่อไป — เช่น "Sandbox quota reached. Pause or kill a sandbox, or retry later." — แทน stack trace ดิบ เพื่อให้ agent แก้ไขตัวเองได้

Secrets, templates, and ports

Secrets. อย่าส่ง credentials เป็น env_vars plaintext แทน:

  1. สร้าง secret ครั้งเดียวด้วย TypeScript SDK (Secret.create()) หรือ console — ค่าดิบไม่เคยเดินทางผ่าน agent หรือ MCP server ดังนั้น การสร้าง secret จึงไม่ใช่ MCP tool โดยตั้งใจ
  2. ค้นหา secrets ที่ผูกได้ด้วย secret_list (metadata เท่านั้น — ค่าไม่เคยออกจากแพลตฟอร์ม)
  3. ผูกตอนสร้าง — secrets: { ANTHROPIC_API_KEY: "anthropic-prod" } บน sandbox_create — หรือทีหลังด้วย sandbox_attach_secret / sandbox_detach_secret

sandbox เห็น proxy token; แพลตฟอร์มสลับเป็น credential จริงเฉพาะสำหรับคำขอขาออกไปยัง hosts ที่ secret อนุญาต

Templates. sandbox สืบทอด vCPU/หน่วยความจำ/ดิสก์จาก template และไม่สามารถแทนที่ได้ตอน sandbox_create เพื่อให้ได้รูปร่างเฉพาะ (เช่น sandbox 4 vCPU) หรือซอฟต์แวร์ที่ติดตั้งไว้ล่วงหน้า สร้าง template ด้วย sandbox_template_create จากนั้น poll sandbox_template_list จนกว่า status เป็น ready ก่อนส่งเป็น from_template

Ports. MCP sandboxes ใหม่ใช้ public เป็นการเข้าถึงค่าเริ่มต้นสำหรับพอร์ตที่เผยแพร่ใหม่; เฉพาะพอร์ตที่เผยแพร่อย่างชัดเจนเท่านั้นที่เข้าถึงได้ ส่ง preview_access: "private" ไปยัง sandbox_create (หรือ sandbox_update) เพื่อเปลี่ยนค่าเริ่มต้นสำหรับพอร์ตในอนาคต พอร์ตที่มีอยู่คงโหมดของตัวเอง เริ่ม server ด้วย sandbox_exec จากนั้นเรียก sandbox_preview_url; เครื่องมือเผยแพร่พอร์ตนั้นหนึ่งพอร์ตแบบ idempotent และใช้โหมดพอร์ตที่คืนมาเพื่อคืนค่า public URL ที่สะอาดหรือ private signed URL ที่หมดอายุ ลิงก์ส่วนตัวค่าเริ่มต้นหนึ่งชั่วโมง; ตั้งค่า expires_in_seconds เป็นค่าตั้งแต่ 1 ถึง 604800 วินาที ดู Preview URLs

ยังไม่มีใน MCP surface

MCP server ครอบคลุมลูป agent ทั่วไป; ตารางด้านบนคือชุดเครื่องมือ v1 ที่สมบูรณ์ ความสามารถ SDK บางอย่างยังไม่เปิดเผย — ใช้ TypeScript SDK โดยตรงสำหรับ:

  • การสร้าง Secret — Secret.create() (MCP server จะ ผูก กับ secret ที่มีอยู่เท่านั้น)
  • คำสั่งแบบสตรีมมิ่งและแบบโต้ตอบ — การสตรีม run() callbacks และ commands.spawn (stdin, สัญญาณ, กระบวนการที่ทำงานยาวนาน)
  • การถ่ายโอนขนาดใหญ่หรือแบบสตรีมมิ่ง — การดาวน์โหลดไดเรกทอรีรองรับสูงสุด 10 MiB ผ่าน sandbox_files_download_dir; เกินกว่านั้น (และสำหรับการอัปโหลดแบบ archive/สตรีมมิ่ง หรือไฟล์เดี่ยวที่เกินขีดจำกัดการอ่าน 1 MiB / การเขียนแบบ inline 8 MiB) ให้ใช้ SDK/CLI (files.downloadDir, การอัปโหลดแบบสตรีมมิ่ง)
  • การเรียกเก็บเงินและการค้นหาผู้ให้บริการ — ข้อมูลการใช้งานและ Provider.list() สำหรับการตั้งค่าผู้ให้บริการ secret

สิ่งเหล่านี้ถูกติดตามเป็นงานติดตามผล

วิธีการทำงาน

เซิร์ฟเวอร์ครอบคลุม TypeScript SDK และเก็บเฉพาะ SUPERSERVE_API_KEY ของ control-plane ของคุณเท่านั้น การเรียกใช้เครื่องมือแต่ละครั้งจะเชื่อมต่อกับ sandbox เป้าหมายตาม ID; SDK จะจัดการ data-plane access token ต่อ sandbox ภายในและหมุนเวียนเมื่อ resume ดังนั้นจึงไม่ถูกเปิดเผยต่อโมเดลหรือส่งกลับในผลลัพธ์ของเครื่องมือ เครื่องมือไม่มีสถานะ — ไม่มี "sandbox ปัจจุบัน" ที่ซ่อนอยู่ — ซึ่งทำให้พฤติกรรมคาดเดาได้ในการเรียกใช้เครื่องมือแบบหลายรอบและแบบขนาน

การแก้ไขปัญหา

  • เครื่องมือไม่ปรากฏ หรือเซิร์ฟเวอร์ไม่เริ่มทำงาน สาเหตุเกือบทั้งหมดมาจาก API key — MCP clients ไม่ สืบทอดตัวแปรสภาพแวดล้อมจาก shell ของคุณ ตั้งค่า SUPERSERVE_API_KEY ในบล็อก env ของเซิร์ฟเวอร์ (ดู การติดตั้ง) ไม่ใช่แค่ในเทอร์มินัลของคุณ
  • Authentication failed คีย์หายไปหรือไม่ถูกต้อง คีย์สำหรับการผลิตเริ่มต้นด้วย ss_live_; สร้างได้ที่หน้า API key
  • การเรียกครั้งแรกช้า npx ดาวน์โหลดแพ็กเกจในการใช้ครั้งแรกและแคชไว้; การเริ่มครั้งต่อไปจะเร็ว
  • ต้องใช้ Node 18+ เซิร์ฟเวอร์ท้องถิ่นทำงานบน Node ผ่าน npx (endpoint โฮสต์ ไม่มีข้อกำหนดรันไทม์ท้องถิ่น)
  • 401 Unauthorized จาก endpoint ที่โฮสต์ bearer token หายไปหรือไม่ใช่คีย์ ss_live_ ที่ถูกต้อง ส่งเป็น Authorization: Bearer ss_live_… (ดู โฮสต์)

เกี่ยวข้อง

หยุดชั่วคราว, resume, และลบ sandboxes Exec, สตรีมมิ่ง, cwd, env, และ timeouts Broker คีย์ผู้ให้บริการโดยไม่เปิดเผยต่อ sandbox ไลบรารีที่ MCP server ครอบคลุม