Superserve Sandbox MCP

Server MCP

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

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

Jalankan dengan dua cara: secara lokal melalui stdio dengan npx, atau terhadap endpoint hosted di https://mcp.superserve.ai tanpa instalasi lokal. Keduanya mengautentikasi 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 sampai ke model.

Mulai Cepat

Tambahkan server ke klien Anda (lihat Instal), 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 di halaman kunci API. Tidak ada instalasi global; npx mengambil server saat pertama kali digunakan.

Instal

Atur `SUPERSERVE_API_KEY` di `env` server — klien MCP tidak mewarisinya dari shell Anda. Lebih suka prompt input rahasia daripada menempelkan kunci mentah di tempat yang didukung klien Anda (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 menggunakan Streamable HTTP — tanpa npx, tanpa Node. Kirim kunci API Superserve Anda sebagai bearer token. Endpoint ini stateless dan terlingkup akun (kunci Anda sudah dipetakan ke tim Anda), dan token data-plane per sandbox tidak pernah meninggalkan server.

Auth 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 Konektor Kustom Claude Desktop, dan mode pengembang ChatGPT tidak menawarkan bidang bearer statis / header kustom (mereka mengharapkan OAuth), yang belum didukung endpoint hosted — gunakan instalasi [lokal](#install) 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 transport dan kunci dikirim sebagai header bearer, bukan variabel env.

Alat

Alat	Fungsinya
sandbox_create	Buat sandbox baru; mengembalikan id-nya. Aktif dan siap segera. Menerima secrets dan aturan egress.
sandbox_update	Ubah metadata atau aturan egress (allow_out/deny_out) sandbox setelah pembuatan.
sandbox_list	Daftar 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 secara otomatis.
sandbox_files_list	Daftar 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 otomatis melanjutkan).
sandbox_kill	Hapus sandbox secara permanen.
sandbox_preview_url	Bangun URL publik untuk port yang mendengarkan (tidak terautentikasi — apa pun di port itu terekspos ke internet).
sandbox_network_log	Audit koneksi keluar sandbox (host, keputusan, byte). Otomatis melanjutkan sandbox yang dijeda.
sandbox_template_list	Daftar templat (citra dasar) yang dapat diluncurkan oleh tim Anda.
sandbox_template_create	Bangun templat kustom dengan bentuk vCPU/memori/disk tertentu atau perangkat lunak pra-instal (asinkron — polling hingga siap).
secret_list	Daftar rahasia tim yang dapat diikat (hanya metadata — tidak pernah nilainya).
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 menerima sandbox_id; pengecualiannya adalah sandbox_create, sandbox_list, sandbox_template_list, sandbox_template_create, dan secret_list. Mulailah dengan salah satunya untuk mendapatkan ID, lalu gunakan di panggilan berikutnya. Alat hanya-baca (sandbox_list, sandbox_info, sandbox_files_read, sandbox_files_list, sandbox_files_download_dir, sandbox_preview_url, sandbox_template_list, secret_list) dianotasi agar klien dapat melewati prompt konfirmasi; sandbox_kill dianotasi sebagai destruktif.

Contoh

Alur agen tipikal untuk "putar 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	Wajib	Deskripsi
SUPERSERVE_API_KEY	Ya	Kunci API Superserve Anda (dimulai dengan ss_live_).
SUPERSERVE_BASE_URL	Tidak	Timpa URL control-plane (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 hanya ada untuk menghangatkan sandbox secara eksplisit.
• Output dibatasi untuk konteks. sandbox_exec memotong stdout dan stderr masing-masing menjadi 32 KiB — hasil yang terpotong menetapkan 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 potongan dengan sandbox_exec (mis. head -c) atau mengunduh seluruh file dengan SDK/CLI. Konten inline sandbox_files_write dibatasi 8 MiB.
• Batas waktu 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 yang ketat, gabungkan dengan deny_out: ["0.0.0.0/0"] (tolak semua, lalu izinkan tujuan yang terdaftar). Atur ini pada sandbox_create atau sandbox_update, dan audit apa yang benar-benar 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 matikan sandbox, atau coba lagi nanti." — alih-alih stack trace mentah, sehingga agen dapat mengoreksi diri.

Rahasia, templat, dan port

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

1. Buat rahasia sekali dengan TypeScript SDK (Secret.create()) atau konsol — nilai mentah tidak pernah melewati 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 proksi; platform menukar kredensial asli hanya untuk permintaan keluar ke host yang diizinkan rahasia.

Templat. Sandbox mewarisi vCPU/memori/disk dari templatnya dan tidak dapat menimpanya saat sandbox_create. Untuk mendapatkan bentuk tertentu (misalnya, sandbox 4 vCPU) atau perangkat lunak pra-instal, bangun templat dengan sandbox_template_create, lalu polling sandbox_template_list hingga status-nya ready sebelum meneruskannya sebagai from_template.

Port. Mulai server di sandbox (sandbox_exec, mis. python3 -m http.server 8000), lalu panggil sandbox_preview_url untuk mendapatkan URL publiknya. Proses apa pun yang terikat ke port dapat dijangkau di https://{port}-{id}.sandbox.superserve.ai dengan tanpa autentikasi — hanya ekspos port yang Anda maksudkan untuk publik.

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 langsung TypeScript SDK untuk:

• Pembuatan rahasia — Secret.create() (server MCP hanya mengikat rahasia yang ada).
• Perintah streaming dan interaktif — streaming callback run() dan commands.spawn (stdin, sinyal, proses yang berjalan lama).
• Transfer besar atau streaming — unduhan direktori didukung hingga 10 MiB melalui sandbox_files_download_dir; lebih dari itu (dan untuk unggahan arsip/streaming atau file tunggal di luar 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 rahasia.

Ini dilacak sebagai tindak lanjut.

Cara kerjanya

Server ini membungkus TypeScript SDK dan hanya menyimpan control-plane SUPERSERVE_API_KEY Anda. Setiap panggilan alat terhubung ke sandbox target berdasarkan ID; SDK mengelola token akses data-plane per sandbox secara internal dan merotasinya saat melanjutkan, sehingga tidak pernah terekspos ke model atau dikembalikan dalam output alat. Alat bersifat stateless — tidak ada "sandbox saat ini" tersembunyi — yang menjaga perilaku tetap dapat diprediksi di seluruh panggilan alat multi-giliran 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. Atur SUPERSERVE_API_KEY di blok env server (lihat Instal), bukan hanya di terminal Anda.
• Authentication failed. Kunci tidak ada 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; permulaan berikutnya cepat.
• Membutuhkan Node 18+. Server lokal berjalan di Node melalui npx. (Titik akhir hosted tidak memiliki persyaratan runtime lokal.)
• 401 Unauthorized dari titik akhir hosted. Token bearer tidak ada atau bukan kunci ss_live_ yang valid. Kirim sebagai Authorization: Bearer ss_live_… (lihat Hosted).

Terkait

Menjeda, melanjutkan, dan menghapus sandbox. Exec, streaming, cwd, env, dan batas waktu. Kunci penyedia broker tanpa mengeksposnya ke sandbox. Pustaka yang dibungkus oleh server MCP.