Superserve Sandbox MCP
ทางการเครื่องเสมือนที่ปลอดภัยสำหรับเอเจนต์ที่โฮสต์โดย Superserve
คุณทำอะไรได้บ้างด้วย Superserve Sandbox MCP?
- สร้างแซนด์บ็อกซ์แบบแยกส่วน — ให้ผู้ช่วยสร้าง Firecracker microVM ด้วย
sandbox_createและสามารถแนบความลับและกฎการส่งออกข้อมูลได้ตามต้องการ - รันคำสั่งเชลล์ภายในแซนด์บ็อกซ์ — ดำเนินการคำสั่งผ่าน
sandbox_execและรับ stdout, stderr และรหัสออก (สามารถดำเนินการต่อแซนด์บ็อกซ์ที่หยุดชั่วคราวได้โดยอัตโนมัติ) - อ่านและเขียนไฟล์ในแซนด์บ็อกซ์ — ใช้
sandbox_files_readและsandbox_files_writeเพื่อตรวจสอบหรือวางไฟล์ โดยมีการสร้างไดเรกทอรีหลักโดยอัตโนมัติ - เปิดเผยจุดสิ้นสุดสาธารณะจากแซนด์บ็อกซ์ — เริ่มกระบวนการเซิร์ฟเวอร์และเรียก
sandbox_preview_urlเพื่อรับ URL ที่เข้าถึงได้สาธารณะสำหรับพอร์ตที่กำลังฟัง - ตรวจสอบการรับส่งข้อมูลเครือข่ายขาออก — ตรวจสอบว่าแซนด์บ็อกซ์ติดต่อโฮสต์ใดบ้าง และได้รับอนุญาตหรือถูกปฏิเสธด้วย
sandbox_network_log - สร้างและจัดการเทมเพลตที่กำหนดเอง — สร้างเทมเพลตที่มี vCPU/หน่วยความจำ/ดิสก์เฉพาะ หรือซอฟต์แวร์ที่ติดตั้งไว้ล่วงหน้าโดยใช้
sandbox_template_createจากนั้นเปิดใช้แซนด์บ็อกซ์จากเทมเพลตดังกล่าว
เอกสาร
MCP Server
สร้าง รัน และจัดการแซนด์บ็อกซ์ Superserve จากไคลเอนต์ MCP ใดๆ
เซิร์ฟเวอร์ MCP ของ Superserve (@superserve/mcp) เปิดเผยพื้นฐานของแซนด์บ็อกซ์เป็นเครื่องมือ Model Context Protocol ดังนั้นไคลเอนต์ที่รองรับ MCP ใดๆ — Claude, Cursor, VS Code, Windsurf, Codex — สามารถสร้างแซนด์บ็อกซ์ รันคำสั่ง อ่านและเขียนไฟล์ สร้างเทมเพลต จัดการซีเคร็ต และควบคุมการเข้าถึงเครือข่ายใน Firecracker microVM ที่แยกส่วนได้
รันได้สองวิธี: ภายในเครื่อง ผ่าน stdio ผ่าน npx หรือเชื่อมต่อกับเอนด์พอยต์ ที่โฮสต์ ที่ https://mcp.superserve.ai โดยไม่ต้องติดตั้งภายในเครื่อง ทั้งสองวิธียืนยันตัวตนด้วย SUPERSERVE_API_KEY ของคุณและระบุเป้าหมายแซนด์บ็อกซ์ต่อการเรียกด้วย ID มันเป็น wrapper แบบบางเหนือ TypeScript SDK ดังนั้นโทเค็น data-plane ต่อแซนด์บ็อกซ์จะไม่ไปถึงโมเดล
เริ่มต้นอย่างรวดเร็ว
เพิ่มเซิร์ฟเวอร์ไปยังไคลเอนต์ของคุณ (ดู ติดตั้ง) จากนั้นขอให้เอเจนต์ "สร้างแซนด์บ็อกซ์และรัน python --version ในนั้น" เอเจนต์จะเรียก sandbox_create จากนั้น sandbox_exec และรายงานผลลัพธ์ — โดยคุณไม่ต้องเขียนโค้ด
คุณต้องมี Superserve API key — สร้างได้ที่หน้า API key ไม่มีการติดตั้งแบบโกลบอล npx จะดึงเซิร์ฟเวอร์เมื่อใช้งานครั้งแรก
ติดตั้ง
ตั้งค่า `SUPERSERVE_API_KEY` ใน `env` ของเซิร์ฟเวอร์ — ไคลเอนต์ MCP จะไม่รับช่วงต่อ จากเชลล์ของคุณ แนะนำให้ใช้การแจ้งเตือนอินพุตลับแทนการวางคีย์ดิบในที่ ที่ไคลเอนต์ของคุณรองรับ (ดู 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` จากสภาพแวดล้อมของคุณ ดังนั้นคีย์ดิบจะไม่ถูกเก็บในไฟล์คอนฟิก (ส่งออกในเชลล์ของคุณก่อน) 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 key ของคุณเป็น bearer token เอนด์พอยต์ไม่มีสถานะและมีขอบเขตตามบัญชี (คีย์ของคุณแมปกับทีมของคุณแล้ว) และโทเค็น data-plane ต่อแซนด์บ็อกซ์จะไม่ออกจากเซิร์ฟเวอร์
```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 และกฎ egress |
sandbox_update | เปลี่ยนเมทาดาทาของแซนด์บ็อกซ์หรือกฎ egress (allow_out/deny_out) หลังจากสร้าง |
sandbox_list | แสดงรายการแซนด์บ็อกซ์ของคุณ (ทำงานและหยุดชั่วคราว) กรองตามเมทาดาทาได้ |
sandbox_info | รับสถานะ ทรัพยากร เมทาดาทา กฎเครือข่าย และการผูกซีเคร็ตของแซนด์บ็อกซ์หนึ่งๆ อ่านอย่างเดียว |
sandbox_exec | รันคำสั่งเชลล์ ส่งคืน stdout, stderr, exit code กู้คืนแซนด์บ็อกซ์ที่หยุดชั่วคราวโดยอัตโนมัติ |
sandbox_files_read | อ่านไฟล์ (ข้อความ UTF-8 หรือ base64 สำหรับไบนารี) |
sandbox_files_write | สร้างหรือเขียนทับไฟล์ ไดเรกทอรีหลักถูกสร้างโดยอัตโนมัติ |
sandbox_files_list | แสดงรายการรายการของไดเรกทอรี (ชื่อ, ประเภท, ขนาด, เวลาแก้ไข) |
sandbox_files_download_dir | ดาวน์โหลดไดเรกทอรีเป็น ZIP base64 (ข้าม symlink) จำกัดที่ 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 key ของคุณ (ขึ้นต้นด้วย ss_live_) |
SUPERSERVE_BASE_URL | ไม่ | แทนที่ URL control-plane (ค่าเริ่มต้น 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 - Egress ควบคุมได้
allow_out(รูปแบบโดเมนหรือ CIDRs) เพิ่มปลายทางที่อนุญาตdeny_out(CIDRs เท่านั้น) บล็อกพวกมันallow_outเพียงอย่างเดียว ไม่ ล็อกดาวน์แซนด์บ็อกซ์ — สำหรับรายการอนุญาตที่เข้มงวด รวมกับdeny_out: ["0.0.0.0/0"](ปฏิเสธทั้งหมด จากนั้นอนุญาตปลายทางที่ระบุไว้) ตั้งค่าเหล่านี้บนsandbox_createหรือsandbox_updateและตรวจสอบสิ่งที่แซนด์บ็อกซ์เข้าถึงจริงด้วยsandbox_network_log - ข้อผิดพลาดนำไปปฏิบัติได้ การเรียกเครื่องมือที่ล้มเหลวส่งคืนข้อความสั้นๆ บอกเอเจนต์ว่าต้องทำอะไรต่อไป — เช่น "ถึงโควตาแซนด์บ็อกซ์แล้ว หยุดชั่วคราวหรือฆ่าแซนด์บ็อกซ์ หรือลองใหม่ภายหลัง" — แทนที่จะเป็น stack trace ดิบ เพื่อให้เอเจนต์แก้ไขตัวเองได้
ซีเคร็ต เทมเพลต และพอร์ต
ซีเคร็ต อย่าส่งข้อมูลประจำตัวเป็น env_vars แบบข้อความธรรมดา ให้ทำดังนี้:
- สร้างซีเคร็ตครั้งเดียวด้วย TypeScript SDK (
Secret.create()) หรือ คอนโซล — ค่าดิบจะไม่เดินทางผ่านเอเจนต์หรือเซิร์ฟเวอร์ MCP ดังนั้น การสร้างซีเคร็ตจึงไม่ใช่เครื่องมือ MCP โดยเจตนา - ค้นพบซีเคร็ตที่ผูกได้ด้วย
secret_list(เมทาดาทาเท่านั้น — ค่าจะไม่ออกจากแพลตฟอร์ม) - ผูกเมื่อสร้าง —
secrets: { ANTHROPIC_API_KEY: "anthropic-prod" }บนsandbox_create— หรือภายหลังด้วย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, สัญญาณ, กระบวนการที่ทำงานนาน) - การถ่ายโอนขนาดใหญ่หรือสตรีมมิ่ง — รองรับการดาวน์โหลดไดเรกทอรีสูงสุด 10 MiB ผ่าน
sandbox_files_download_dir; เกินกว่านั้น (และสำหรับการอัปโหลดแบบเก็บถาวร/สตรีมมิ่งหรือไฟล์เดี่ยวที่เกินขีดจำกัดการอ่าน 1 MiB / การเขียนในบรรทัด 8 MiB) ใช้ SDK/CLI (files.downloadDir, การอัปโหลดแบบสตรีมมิ่ง) - การเรียกเก็บเงินและการค้นพบผู้ให้บริการ — ข้อมูลการใช้งานและ
Provider.list()สำหรับการตั้งค่าผู้ให้บริการซีเคร็ต
สิ่งเหล่านี้ถูกติดตามเป็นการติดตามผล
มันทำงานอย่างไร
เซิร์ฟเวอร์นี้ครอบคลุม TypeScript SDK และเก็บเฉพาะ SUPERSERVE_API_KEY ของ control-plane ของคุณเท่านั้น การเรียกใช้เครื่องมือแต่ละครั้งจะเชื่อมต่อกับแซนด์บ็อกซ์เป้าหมายด้วย ID; SDK จะจัดการ โทเค็นการเข้าถึง data-plane ต่อแซนด์บ็อกซ์ภายในและหมุนเวียนเมื่อกลับมาทำงานต่อ จึงไม่มีการเปิดเผยต่อโมเดลหรือส่งคืนในผลลัพธ์ของเครื่องมือ เครื่องมือไม่มีสถานะ — ไม่มี "แซนด์บ็อกซ์ปัจจุบัน" ที่ซ่อนอยู่ — ซึ่งทำให้พฤติกรรมคาดการณ์ได้ตลอดการเรียกใช้เครื่องมือแบบหลายรอบและแบบขนาน
การแก้ไขปัญหา
- เครื่องมือไม่ปรากฏ หรือเซิร์ฟเวอร์ไม่เริ่มทำงาน สาเหตุเกือบทั้งหมดมาจาก API key — ไคลเอนต์ MCP ไม่ สืบทอดตัวแปรสภาพแวดล้อมจากเชลล์ของคุณ ตั้งค่า
SUPERSERVE_API_KEYในบล็อกenvของเซิร์ฟเวอร์ (ดู ติดตั้ง) ไม่ใช่แค่ในเทอร์มินัลของคุณ Authentication failedคีย์หายไปหรือไม่ถูกต้อง คีย์สำหรับการใช้งานจริงขึ้นต้นด้วยss_live_; สร้างได้ที่หน้า API key- การเรียกครั้งแรกช้า
npxดาวน์โหลดแพ็กเกจเมื่อใช้งานครั้งแรกและแคชไว้; การเริ่มครั้งต่อๆ ไปจะเร็ว - ต้องใช้ Node 18+ เซิร์ฟเวอร์ภายในรันบน Node ผ่าน
npx(ปลายทางแบบ โฮสต์ ไม่มีข้อกำหนดรันไทม์ภายใน) 401 Unauthorizedจากปลายทางแบบโฮสต์ โทเค็น Bearer หายไปหรือไม่ใช่คีย์ss_live_ที่ถูกต้อง ส่งเป็นAuthorization: Bearer ss_live_…(ดู โฮสต์)