Superserve Sandbox MCP

Server MCP

Buat, jalankan, dan kelola sandbox Superserve dari klien MCP mana pun.

Ingin membiarkan agen membuat sandbox sendiri? Server MCP ini melakukannya.

Server MCP Superserve (@superserve/mcp) mengekspos primitif sandbox sebagai alat Model Context Protocol, sehingga klien mana pun yang mendukung MCP — Claude, Cursor, VS Code, Windsurf, Codex — dapat membuat sandbox, menjalankan perintah, membaca dan menulis file, membangun template, mengelola rahasia, dan mengontrol akses jaringan dalam microVM Firecracker yang terisolasi.

Jalankan dengan dua cara: secara lokal melalui stdio via npx, atau terhadap endpoint hosted di https://mcp.superserve.ai tanpa instalasi lokal. Keduanya melakukan autentikasi dengan SUPERSERVE_API_KEY Anda dan menargetkan sandbox per panggilan berdasarkan ID. Ini adalah pembungkus tipis di atas TypeScript SDK, sehingga token data-plane per-sandbox tidak pernah mencapai model.

Memulai Cepat

Tambahkan server ke klien Anda (lihat Instalasi), lalu minta agen untuk "buat sandbox dan jalankan python --version di dalamnya." Agen memanggil sandbox_create, lalu sandbox_exec, dan melaporkan hasilnya — tanpa kode dari Anda.

Anda memerlukan kunci API Superserve — buat satu di halaman kunci API. Tidak ada instalasi global; npx mengambil server pada penggunaan pertama.

Instalasi

Catatan

Atur SUPERSERVE_API_KEY di env server — klien MCP tidak mewarisinya dari shell Anda. Utamakan prompt input rahasia daripada menempelkan kunci mentah di mana klien Anda mendukungnya (lihat VS Code di bawah).

```bash theme={"theme":{"light":"github-light","dark":"vitesse-dark"}} claude mcp add superserve \ --env SUPERSERVE_API_KEY=ss_live_xxxxxxxxxxxxxxxx \ -- npx -y @superserve/mcp ``` Tambahkan ke `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" }
    }
  }
}
```

Tambahkan ke `.cursor/mcp.json` (proyek) atau `~/.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" }
    }
  }
}
```

Tambahkan ke `.vscode/mcp.json`. Blok `inputs` meminta kunci alih-alih menyimpannya dalam teks biasa:

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

Tambahkan ke `~/.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" }
    }
  }
}
```

Tambahkan ke `~/.codex/config.toml`. `env_vars` meneruskan `SUPERSERVE_API_KEY` dari lingkungan Anda, sehingga kunci mentah tidak disimpan dalam file konfigurasi (ekspor di shell Anda terlebih dahulu). Codex juga membaca `instructions` server untuk panduan alur kerja lintas-alat.

```toml theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
[mcp_servers.superserve]
command = "npx"
args = ["-y", "@superserve/mcp"]
env_vars = ["SUPERSERVE_API_KEY"]
```

Untuk endpoint [hosted](#hosted-remote), gunakan `url = "https://mcp.superserve.ai"` dengan `bearer_token_env_var = "SUPERSERVE_API_KEY"`.

Hosted (jarak jauh)

Tidak ingin menjalankan apa pun secara lokal? Endpoint hosted di https://mcp.superserve.ai berbicara Streamable HTTP — tanpa npx, tanpa Node. Kirim kunci API Superserve Anda sebagai token bearer. Endpoint bersifat stateless dan terikat akun (kunci Anda sudah memetakan ke tim Anda), dan token data-plane per-sandbox tidak pernah meninggalkan server.

Catatan

Autentikasi Bearer berfungsi di klien mana pun yang memungkinkan Anda mengatur header permintaan — Claude Code, Cursor, VS Code, dan konektor Anthropic Messages API. Claude.ai, UI Custom Connector Claude Desktop, dan mode pengembang ChatGPT tidak menawarkan bidang bearer statis / header khusus (mereka mengharapkan OAuth), yang tidak didukung oleh endpoint hosted — gunakan instalasi lokal di sana.

```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" ``` Tambahkan ke `.cursor/mcp.json` (proyek) atau `~/.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" }
    }
  }
}
```

Tambahkan ke `.vscode/mcp.json`. Blok `inputs` meminta kunci alih-alih menyimpannya dalam teks biasa:

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

Teruskan sebagai konektor dalam permintaan [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"
    }
  ]
}
```

Alat dan perilaku yang sama dengan server lokal — satu-satunya perbedaan adalah transportasi dan bahwa kunci berjalan sebagai header bearer alih-alih variabel env.

Alat

Alat	Fungsinya
sandbox_create	Membuat sandbox baru; mengembalikan id-nya. Menerima secrets, aturan egress, dan preview_access.
sandbox_update	Mengubah metadata, aturan egress, jendela siklus hidup, atau preview_access.
sandbox_list	Mencantumkan sandbox Anda (aktif dan dijeda), dapat difilter berdasarkan metadata.
sandbox_info	Mendapatkan status, sumber daya, metadata, aturan jaringan, dan pengikatan rahasia satu sandbox. Hanya-baca.
sandbox_exec	Menjalankan perintah shell; mengembalikan stdout, stderr, kode keluar. Secara otomatis melanjutkan sandbox yang dijeda.
sandbox_files_read	Membaca file (teks UTF-8, atau base64 untuk biner).
sandbox_files_write	Membuat atau menimpa file. Direktori induk dibuat secara otomatis.
sandbox_files_list	Mencantumkan entri direktori (nama, jenis, ukuran, waktu modifikasi).
sandbox_files_download_dir	Mengunduh direktori sebagai ZIP base64 (symlink dilewati). Dibatasi 10 MiB; lebih besar → SDK/CLI.
sandbox_pause	Menjeda sandbox; status dipertahankan.
sandbox_resume	Melanjutkan sandbox yang dijeda (biasanya tidak perlu — exec melanjutkan otomatis).
sandbox_kill	Menghapus sandbox secara permanen.
sandbox_preview_url	Menerbitkan port dan mengembalikan URL publik yang bersih atau URL pribadi bertanda tangan yang kedaluwarsa.
sandbox_network_log	Mengaudit koneksi keluar sandbox (host, keputusan, byte) tanpa melanjutkannya.
sandbox_computer	Menggerakkan sandbox desktop GUI: tangkapan layar, mouse, keyboard, gulir, ubah ukuran, URL penampil. Satu tindakan per panggilan.
sandbox_template_list	Mencantumkan template (gambar dasar) yang dapat diluncurkan tim Anda.
sandbox_template_create	Membangun template khusus dengan bentuk vCPU/memori/disk tertentu atau perangkat lunak terinstal (async — polling hingga siap).
secret_list	Mencantumkan rahasia tim yang dapat diikat (hanya metadata — tidak pernah nilai).
sandbox_attach_secret	Mengikat rahasia tersimpan ke sandbox yang berjalan di bawah variabel env.
sandbox_detach_secret	Menghapus pengikatan rahasia dari sandbox.

Sebagian besar alat memerlukan sandbox_id; pengecualiannya adalah sandbox_create, sandbox_list, sandbox_template_list, sandbox_template_create, dan secret_list. Mulailah dengan salah satu dari itu untuk mendapatkan ID, lalu teruskan ke panggilan berikutnya. Alat hanya-baca (sandbox_list, sandbox_info, sandbox_files_read, sandbox_files_list, sandbox_files_download_dir, sandbox_network_log, sandbox_template_list, secret_list) dianotasi sehingga klien dapat melewati prompt konfirmasi; sandbox_preview_url adalah penulisan idempoten karena menerbitkan port yang diminta, dan sandbox_kill dianotasi destruktif.

Contoh

Alur agen yang khas untuk "nyalakan sandbox, tulis skrip Python yang mencetak bilangan prima pertama, dan jalankan":

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

Setelah selesai, agen dapat sandbox_pause (status dipertahankan, lebih murah untuk disimpan) atau sandbox_kill (permanen).

Konfigurasi

Variabel	Diperlukan	Deskripsi
SUPERSERVE_API_KEY	Ya	Kunci API Superserve Anda (dimulai dengan ss_live_).
SUPERSERVE_BASE_URL	Tidak	Menimpa URL bidang kontrol (default ke https://api.superserve.ai).

Perilaku dan batasan

• Lanjutkan otomatis. sandbox_exec dan alat file secara transparan melanjutkan sandbox yang dijeda, sehingga agen tidak perlu memanggil sandbox_resume terlebih dahulu. sandbox_resume ada hanya untuk menghangatkan sandbox secara eksplisit.
• Output dibatasi untuk konteks. sandbox_exec memotong stdout dan stderr menjadi 32 KiB masing-masing — hasil yang dipotong mengatur truncated: true dan melaporkan panjang byte asli. sandbox_files_read menolak file yang lebih besar dari 1 MiB (tidak mengembalikan konten parsial); kesalahan memberi tahu Anda untuk membaca irisan dengan sandbox_exec (mis. head -c) atau mengunduh seluruh file dengan SDK/CLI. Konten inline sandbox_files_write dibatasi 8 MiB.
• Waktu tunggu perintah default adalah 60 detik, dibatasi hingga 10 menit. Timpa per panggilan dengan timeout_ms.
• Egress dapat dikontrol. allow_out (pola domain, IP, atau CIDR) menambahkan tujuan yang diizinkan; deny_out (IP atau CIDR, tanpa domain) memblokirnya. allow_out saja tidak mengunci sandbox — untuk daftar izin ketat, gabungkan dengan deny_out: ["0.0.0.0/0"] (tolak semua, lalu izinkan tujuan yang tercantum). Jika daftar izin memiliki aturan domain atau beban kerja menyelesaikan nama host, juga izinkan resolver DNS sandbox, 1.1.1.1/32 dan 8.8.8.8/32, karena tolak-semua juga memblokir DNS; tinggalkan mereka dari daftar izin khusus-IP, di mana resolver yang diizinkan hanyalah saluran keluar ekstra. Atur ini pada sandbox_create atau sandbox_update, dan audit apa yang sebenarnya dijangkau sandbox dengan sandbox_network_log.
• Kesalahan dapat ditindaklanjuti. Panggilan alat yang gagal mengembalikan pesan singkat yang memberi tahu agen apa yang harus dilakukan selanjutnya — mis. "Kuota sandbox tercapai. Jeda atau hentikan sandbox, atau coba lagi nanti." — alih-alih jejak tumpukan mentah, sehingga agen dapat mengoreksi diri sendiri.

Rahasia, template, dan port

Rahasia. Jangan meneruskan kredensial sebagai env_vars teks biasa. Sebagai gantinya:

1. Buat rahasia sekali dengan TypeScript SDK (Secret.create()) atau konsol — nilai mentah tidak pernah melalui agen atau server MCP, jadi pembuatan rahasia sengaja bukan alat MCP.
2. Temukan rahasia yang dapat diikat dengan secret_list (hanya metadata — nilai tidak pernah meninggalkan platform).
3. Ikat saat pembuatan — secrets: { ANTHROPIC_API_KEY: "anthropic-prod" } pada sandbox_create — atau nanti dengan sandbox_attach_secret / sandbox_detach_secret.

Sandbox melihat token proxy; platform menukar kredensial asli hanya untuk permintaan keluar ke host yang diizinkan rahasia.

Template. Sandbox mewarisi vCPU/memori/disk dari template-nya dan tidak dapat menimpanya pada waktu sandbox_create. Untuk mendapatkan bentuk tertentu (misalnya, sandbox 4 vCPU) atau perangkat lunak terinstal, bangun template dengan sandbox_template_create, lalu polling sandbox_template_list hingga status-nya adalah ready sebelum meneruskannya sebagai from_template.

Port. Sandbox MCP baru menggunakan public sebagai akses default untuk port yang baru diterbitkan; hanya port yang diterbitkan secara eksplisit yang dapat dijangkau. Teruskan preview_access: "private" ke sandbox_create (atau sandbox_update) untuk mengubah default untuk port masa depan. Port yang ada mempertahankan mode mereka sendiri. Mulai server dengan sandbox_exec, lalu panggil sandbox_preview_url; alat secara idempoten menerbitkan satu port itu dan menggunakan mode port yang dikembalikan untuk mengembalikan URL publik yang bersih atau URL pribadi bertanda tangan yang kedaluwarsa. Tautan pribadi default satu jam; atur expires_in_seconds ke nilai dari 1 hingga 604800 detik. Lihat URL Pratinjau.

Penggunaan komputer

sandbox_computer menggerakkan desktop GUI di sandbox yang dibuat dari template desktop seperti superserve/desktop. Dibutuhkan satu action per panggilan dalam kosakata yang dihasilkan model penggunaan komputer: 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, dan stream_url. Tindakan penunjuk memerlukan coordinate: [x, y] dalam piksel layar (asal kiri-atas); key dan type memerlukan text; scroll memerlukan scroll_direction dan opsional 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" }

Tindakan input mengembalikan tangkapan layar baru dari hasilnya, sehingga giliran bertindak-lalu-lihat model adalah satu panggilan alat; teruskan screenshot_after: false saat mengirim beberapa tindakan berturut-turut. wait berhenti sejenak selama duration_ms (dibatasi 10 detik) tanpa permintaan ke sandbox. stream_url mengembalikan penampil browser langsung untuk desktop di bawah kebijakan pratinjau sandbox.

Jika tindakan input gagal, input mungkin sudah dikirim. Alat mengatakan demikian dan meminta agen untuk mengambil tangkapan layar sebelum mengulanginya. Lihat Panduan Desktop untuk permukaan SDK yang mendasarinya.

Belum ada di permukaan MCP

Server MCP ini mencakup loop agen umum; tabel di atas adalah kumpulan alat v1 yang lengkap. Beberapa kemampuan SDK belum diekspos — gunakan TypeScript SDK secara langsung untuk:

• Pembuatan secret — Secret.create() (server MCP hanya mengikat secret yang sudah ada).
• Perintah streaming dan interaktif — streaming callback run() dan commands.spawn (stdin, sinyal, proses berjalan lama).
• Transfer besar atau streaming — unduhan direktori didukung hingga 10 MiB melalui sandbox_files_download_dir; di luar itu (dan untuk unggahan arsip/streaming atau file tunggal yang melebihi batas baca 1 MiB / tulis inline 8 MiB), gunakan SDK/CLI (files.downloadDir, unggahan streaming).
• Penagihan dan penemuan penyedia — data penggunaan dan Provider.list() untuk pengaturan penyedia secret.

Ini dilacak sebagai tindak lanjut.

Cara kerjanya

Server membungkus TypeScript SDK dan hanya menyimpan SUPERSERVE_API_KEY bidang kontrol Anda. Setiap panggilan alat terhubung ke sandbox target berdasarkan ID; SDK mengelola token akses bidang data per-sandbox secara internal dan merotasinya saat dilanjutkan, sehingga tidak pernah diekspos ke model atau dikembalikan dalam output alat. Alat bersifat stateless — tidak ada "sandbox saat ini" yang tersembunyi — yang menjaga perilaku tetap dapat diprediksi di seluruh panggilan alat multi-putaran dan paralel.

Pemecahan masalah

• Alat tidak muncul, atau server gagal dimulai. Kunci API hampir selalu menjadi penyebabnya — klien MCP tidak mewarisi variabel lingkungan dari shell Anda. Setel SUPERSERVE_API_KEY di blok env server (lihat Instal), bukan hanya di terminal Anda.
• Authentication failed. Kunci hilang atau tidak valid. Kunci produksi dimulai dengan ss_live_; buat satu di halaman kunci API.
• Panggilan pertama lambat. npx mengunduh paket pada penggunaan pertama dan menyimpannya dalam cache; mulai berikutnya cepat.
• Membutuhkan Node 18+. Server lokal berjalan di Node melalui npx. (Endpoint hosted tidak memiliki persyaratan runtime lokal.)
• 401 Unauthorized dari endpoint hosted. Token pembawa hilang atau bukan kunci ss_live_ yang valid. Kirim sebagai Authorization: Bearer ss_live_… (lihat Hosted).

Terkait

Jeda, lanjutkan, dan hapus sandbox. Exec, streaming, cwd, env, dan timeout. Broker kunci penyedia tanpa mengeksposnya ke sandbox. Pustaka yang dibungkus oleh server MCP.

Dokumentasi ini dibangun dan dihosting di Mintlify, platform dokumentasi pengembang.