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 bisa 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 melalui 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 akan 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

Setel SUPERSERVE_API_KEY di env server — klien MCP tidak mewarisinya dari shell Anda. Utamakan prompt input rahasia daripada menempelkan kunci mentah jika 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 di 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 menggunakan Streamable HTTP — tanpa npx, tanpa Node. Kirim kunci API Superserve Anda sebagai token bearer. Endpoint ini tanpa status dan terikat akun (kunci Anda sudah terpetakan 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 kolom bearer statis / header kustom (mereka mengharapkan OAuth), yang belum 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	Fungsi
sandbox_create	Buat sandbox baru; mengembalikan id-nya. Menerima secrets, aturan egress, dan preview_access.
sandbox_update	Ubah metadata, aturan egress, jendela siklus hidup, atau preview_access.
sandbox_list	Daftarkan sandbox Anda (aktif dan dijeda), dapat difilter berdasarkan metadata.
sandbox_info	Dapatkan status, sumber daya, metadata, aturan jaringan, dan binding rahasia satu sandbox. Hanya-baca.
sandbox_exec	Jalankan perintah shell; mengembalikan stdout, stderr, kode keluar. Otomatis melanjutkan sandbox yang dijeda.
sandbox_files_read	Baca file (teks UTF-8, atau base64 untuk biner).
sandbox_files_write	Buat atau timpa file. Direktori induk dibuat otomatis.
sandbox_files_list	Daftarkan entri direktori (nama, tipe, ukuran, waktu modifikasi).
sandbox_files_download_dir	Unduh direktori sebagai ZIP base64 (symlink dilewati). Dibatasi 10 MiB; lebih besar → SDK/CLI.
sandbox_pause	Jeda sandbox; status dipertahankan.
sandbox_resume	Lanjutkan sandbox yang dijeda (biasanya tidak perlu — exec melanjutkan otomatis).
sandbox_kill	Hapus sandbox secara permanen.
sandbox_preview_url	Publikasikan port dan kembalikan URL publik bersih atau URL pribadi bertanda tangan yang kedaluwarsa.
sandbox_network_log	Audit koneksi keluar sandbox (host, verdict, byte) tanpa melanjutkannya.
sandbox_template_list	Daftarkan template (gambar dasar) yang dapat digunakan tim Anda untuk meluncurkan.
sandbox_template_create	Bangun template kustom dengan bentuk vCPU/memori/disk tertentu atau perangkat lunak terinstal (async — polling hingga siap).
secret_list	Daftarkan rahasia tim yang dapat diikat (metadata saja — tidak pernah nilai).
sandbox_attach_secret	Ikat rahasia tersimpan ke sandbox yang berjalan di bawah variabel env.
sandbox_detach_secret	Hapus binding 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 memublikasikan 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	Timpa 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.
• Timeout perintah default adalah 60 detik, dibatasi maksimal 10 menit. Timpa per panggilan dengan timeout_ms.
• Egress dapat dikontrol. allow_out (pola domain atau CIDR) menambahkan tujuan yang diizinkan; deny_out (hanya CIDR) 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 terdaftar). Setel 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 stack trace mentah, sehingga agen dapat mengoreksi diri sendiri.

Rahasia, template, dan port

Rahasia. Jangan teruskan 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, sehingga pembuatan rahasia sengaja bukan alat MCP.
2. Temukan rahasia yang dapat diikat dengan secret_list (metadata saja — 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 untuk rahasia tersebut.

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 menjadi ready sebelum meneruskannya sebagai from_template.

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

Belum ada di permukaan MCP

Server MCP mencakup loop agen umum; tabel di atas adalah set alat v1 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 run() callback 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 data-plane per-sandbox secara internal dan memutarnya saat dilanjutkan, sehingga tidak pernah terekspos 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 Instalasi), 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 bearer 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 batas waktu. Broker kunci penyedia tanpa mengeksposnya ke sandbox. Pustaka yang dibungkus oleh server MCP.