Superserve Sandbox MCP

MCP Sunucusu

Superserve sandbox'larını herhangi bir MCP istemcisinden oluşturun, çalıştırın ve yönetin.

Bir ajanın kendi başına sandbox oluşturmasını mı istiyorsunuz? Bu MCP sunucusu tam olarak bunu yapar.

Superserve MCP sunucusu (@superserve/mcp), sandbox temel öğelerini Model Context Protocol araçları olarak sunar; böylece MCP destekli herhangi bir istemci — Claude, Cursor, VS Code, Windsurf, Codex — izole bir Firecracker microVM içinde sandbox oluşturabilir, komut çalıştırabilir, dosya okuyup yazabilir, şablonlar oluşturabilir, sırları yönetebilir ve ağ erişimini kontrol edebilir.

İki şekilde çalıştırın: npx üzerinden yerel olarak stdio ile veya yerel kurulum gerektirmeyen https://mcp.superserve.ai adresindeki barındırılan uç noktaya karşı. Her ikisi de SUPERSERVE_API_KEY ile kimlik doğrular ve her çağrıda kimliğe göre bir sandbox'ı hedefler. TypeScript SDK üzerinde ince bir sarmalayıcıdır; bu nedenle sandbox başına veri düzlemi belirteci asla modele ulaşmaz.

Hızlı Başlangıç

Sunucuyu istemcinize ekleyin (bkz. Kurulum), ardından ajandan "bir sandbox oluştur ve içinde python --version çalıştır" demesini isteyin. Ajan sandbox_create ve ardından sandbox_exec çağırır ve sonucu bildirir — sizden hiçbir kod gerekmez.

Bir Superserve API anahtarına ihtiyacınız var — API anahtarı sayfasından bir tane oluşturun. Küresel bir kurulum yoktur; npx sunucuyu ilk kullanımda getirir.

Kurulum

Not

Sunucunun env içinde SUPERSERVE_API_KEY değerini ayarlayın — MCP istemcileri bunu kabuğunuzdan devralmaz. İstemciniz destekliyorsa, ham anahtarı yapıştırmak yerine gizli giriş istemini tercih edin (aşağıdaki VS Code'a bakın).

```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` dosyasına ekleyin (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` (proje) veya `~/.cursor/mcp.json` (genel) dosyasına ekleyin:

```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` dosyasına ekleyin. `inputs` bloğu, anahtarı düz metin olarak saklamak yerine giriş ister:

```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` dosyasına ekleyin:

```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` dosyasına ekleyin. `env_vars`, `SUPERSERVE_API_KEY` değerini ortamınızdan iletir; böylece ham anahtar yapılandırma dosyasında saklanmaz (önce kabuğunuzda dışa aktarın). Codex ayrıca araçlar arası iş akışı rehberliği için sunucunun `instructions` değerini okur.

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

[Barındırılan](#hosted-remote) uç nokta için `bearer_token_env_var = "SUPERSERVE_API_KEY"` ile `url = "https://mcp.superserve.ai"` kullanın.

Barındırılan (uzak)

Yerel olarak hiçbir şey çalıştırmak istemiyor musunuz? https://mcp.superserve.ai adresindeki barındırılan uç nokta Streamable HTTP protokolünü konuşur — npx veya Node gerekmez. Superserve API anahtarınızı taşıyıcı belirteç olarak gönderin. Uç nokta durumsuzdur ve hesap kapsamlıdır (anahtarınız zaten ekibinize eşlenir) ve sandbox başına veri düzlemi belirteci asla sunucudan çıkmaz.

Not

Taşıyıcı kimlik doğrulaması, istek başlığı ayarlamanıza izin veren herhangi bir istemcide çalışır — Claude Code, Cursor, VS Code ve Anthropic Messages API bağlayıcısı. Claude.ai, Claude Desktop'ın Özel Bağlayıcı arayüzü ve ChatGPT geliştirici modu statik taşıyıcı / özel başlık alanı sunmaz (OAuth beklerler), barındırılan uç nokta henüz bunu desteklemez — orada yerel kurulumu kullanın.

```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` (proje) veya `~/.cursor/mcp.json` (genel) dosyasına ekleyin:

```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` dosyasına ekleyin. `inputs` bloğu, anahtarı düz metin olarak saklamak yerine giriş ister:

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

Bir [Anthropic Messages API](https://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector) isteğinde bağlayıcı olarak iletin:

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

Yerel sunucuyla aynı araçlar ve davranış — tek fark taşıma ve anahtarın bir env değişkeni yerine taşıyıcı başlığı olarak gitmesidir.

Araçlar

Araç	Ne yapar
sandbox_create	Yeni bir sandbox oluşturur; id değerini döndürür. secrets, egress kuralları ve preview_access kabul eder.
sandbox_update	Meta verileri, egress kurallarını, yaşam döngüsü pencerelerini veya preview_access değiştirir.
sandbox_list	Sandbox'larınızı (etkin ve duraklatılmış) listeler, meta verilere göre filtrelenebilir.
sandbox_info	Bir sandbox'ın durumunu, kaynaklarını, meta verilerini, ağ kurallarını ve sır bağlamalarını alır. Salt okunur.
sandbox_exec	Bir kabuk komutu çalıştırır; stdout, stderr, çıkış kodunu döndürür. Duraklatılmış bir sandbox'ı otomatik olarak sürdürür.
sandbox_files_read	Bir dosyayı okur (UTF-8 metin veya ikili için base64).
sandbox_files_write	Bir dosya oluşturur veya üzerine yazar. Üst dizinler otomatik olarak oluşturulur.
sandbox_files_list	Bir dizinin girdilerini listeler (ad, tür, boyut, değiştirilme zamanı).
sandbox_files_download_dir	Bir dizini base64 ZIP olarak indirir (sembolik bağlantılar atlanır). 10 MiB ile sınırlıdır; daha büyük → SDK/CLI.
sandbox_pause	Bir sandbox'ı duraklatır; durum korunur.
sandbox_resume	Duraklatılmış bir sandbox'ı sürdürür (genellikle gerekmez — exec otomatik sürdürür).
sandbox_kill	Bir sandbox'ı kalıcı olarak siler.
sandbox_preview_url	Bir bağlantı noktası yayınlar ve temiz bir genel URL veya süresi dolan özel imzalı URL döndürür.
sandbox_network_log	Bir sandbox'ın giden bağlantılarını (ana bilgisayar, karar, bayt) sürdürmeden denetler.
sandbox_computer	Bir GUI masaüstü sandbox'ını yönlendirir: ekran görüntüsü, fare, klavye, kaydırma, yeniden boyutlandırma, görüntüleyici URL'si. Çağrı başına bir eylem.
sandbox_template_list	Ekibinizin başlatabileceği şablonları (temel görüntüler) listeler.
sandbox_template_create	Belirli bir vCPU/bellek/disk şekline veya önceden yüklenmiş yazılıma sahip özel bir şablon oluşturur (zaman uyumsuz — hazır olana kadar yoklayın).
secret_list	Bağlanabilir ekip sırlarını listeler (yalnızca meta veriler — asla değerler).
sandbox_attach_secret	Saklanan bir sırrı çalışan bir sandbox'a bir ortam değişkeni altında bağlar.
sandbox_detach_secret	Bir sandbox'tan sır bağlamasını kaldırır.

Çoğu araç bir sandbox_id alır; istisnalar sandbox_create, sandbox_list, sandbox_template_list, sandbox_template_create ve secret_list'dır. Bunlardan biriyle başlayıp bir kimlik alın, ardından sonraki çağrılara iletin. Salt okunur araçlar (sandbox_list, sandbox_info, sandbox_files_read, sandbox_files_list, sandbox_files_download_dir, sandbox_network_log, sandbox_template_list, secret_list) istemcilerin onay istemlerini atlayabilmesi için açıklanmıştır; sandbox_preview_url istenen bağlantı noktasını yayınladığı için idempotent bir yazmadır ve sandbox_kill yıkıcı olarak açıklanmıştır.

Örnek

"Bir sandbox başlat, ilk asal sayıları yazdıran bir Python betiği yaz ve çalıştır" için tipik bir ajan akışı:

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

Bittiğinde, ajan sandbox_pause (durum korunur, etrafta tutmak daha ucuzdur) veya sandbox_kill (kalıcı) yapabilir.

Yapılandırma

Değişken	Gerekli	Açıklama
SUPERSERVE_API_KEY	Evet	Superserve API anahtarınız (ss_live_ ile başlar).
SUPERSERVE_BASE_URL	Hayır	Kontrol düzlemi URL'sini geçersiz kılar (varsayılan https://api.superserve.ai'dır).

Davranış ve sınırlar

• Otomatik sürdürme. sandbox_exec ve dosya araçları duraklatılmış bir sandbox'ı şeffaf bir şekilde sürdürür; böylece ajanların önce sandbox_resume çağırmasına gerek kalmaz. sandbox_resume yalnızca bir sandbox'ı açıkça ısıtmak için vardır.
• Çıktı bağlam için sınırlandırılmıştır. sandbox_exec, stdout ve stderr'i her biri 32 KiB'ye kadar kısaltır — kısaltılmış bir sonuç truncated: true ayarlar ve orijinal bayt uzunluğunu bildirir. sandbox_files_read, 1 MiB'den büyük dosyaları reddeder (kısmi içerik döndürmez); hata, sandbox_exec ile bir dilim okumanızı (örn. head -c) veya SDK/CLI ile tüm dosyayı indirmenizi söyler. sandbox_files_write satır içi içerik 8 MiB ile sınırlıdır.
• Varsayılan komut zaman aşımı 60 saniyedir, en fazla 10 dakika. Çağrı başına timeout_ms ile geçersiz kılın.
• Egress kontrol edilebilir. allow_out (alan adı desenleri, IP'ler veya CIDR'ler) izin verilen hedefler ekler; deny_out (IP'ler veya CIDR'ler, alan adı yok) bunları engeller. allow_out tek başına bir sandbox'ı kilitlemez — sıkı bir izin listesi için, deny_out: ["0.0.0.0/0"] ile birleştirin (tümünü reddet, ardından listelenen hedeflere izin ver). İzin listesinde alan adı kuralları varsa veya iş yükü ana bilgisayar adlarını çözümlüyorsa, sandbox'ın DNS çözümleyicilerine de izin verin, 1.1.1.1/32 ve 8.8.8.8/32, çünkü tümünü reddet DNS'i de engeller; bunları yalnızca IP izin listesinden çıkarın, burada izin verilen bir çözümleyici yalnızca ek bir giden kanaldır. Bunları sandbox_create veya sandbox_update üzerinde ayarlayın ve bir sandbox'ın gerçekte neye ulaştığını sandbox_network_log ile denetleyin.
• Hatalar eyleme dönüştürülebilir. Başarısız bir araç çağrısı, ajana ne yapması gerektiğini söyleyen kısa bir mesaj döndürür — örn. "Sandbox kotasına ulaşıldı. Bir sandbox'ı duraklatın veya öldürün ya da daha sonra tekrar deneyin." — ham bir yığın izi yerine, böylece ajan kendini düzeltebilir.

Sırlar, şablonlar ve bağlantı noktaları

Sırlar. Kimlik bilgilerini düz metin env_vars olarak iletmeyin. Bunun yerine:

1. Sırrı bir kez TypeScript SDK (Secret.create()) veya konsol ile oluşturun — ham değer asla ajan veya MCP sunucusu üzerinden geçmez, bu nedenle sır oluşturma kasıtlı olarak bir MCP aracı değildir.
2. Bağlanabilir sırları secret_list ile keşfedin (yalnızca meta veriler — değerler asla platformdan çıkmaz).
3. Oluşturma sırasında bağlayın — sandbox_create üzerinde secrets: { ANTHROPIC_API_KEY: "anthropic-prod" } — veya daha sonra sandbox_attach_secret / sandbox_detach_secret ile.

Sandbox bir proxy belirteci görür; platform gerçek kimlik bilgisini yalnızca sırrın izin verilen ana bilgisayarlarına yapılan giden istekler için değiştirir.

Şablonlar. Bir sandbox, vCPU/bellek/diskini şablonundan miras alır ve sandbox_create zamanında bunları geçersiz kılamaz. Belirli bir şekil (örneğin, 4 vCPU sandbox) veya önceden yüklenmiş yazılım elde etmek için sandbox_template_create ile bir şablon oluşturun, ardından status değeri ready olana kadar sandbox_template_list yoklayın ve from_template olarak iletin.

Bağlantı noktaları. Yeni MCP sandbox'ları, yeni yayınlanan bağlantı noktaları için varsayılan erişim olarak public kullanır; yalnızca açıkça yayınlanan bağlantı noktalarına erişilebilir. Gelecekteki bağlantı noktaları için varsayılanı değiştirmek üzere sandbox_create (veya sandbox_update) çağrısına preview_access: "private" iletin. Mevcut bağlantı noktaları kendi modunu korur. Sunucuyu sandbox_exec ile başlatın, ardından sandbox_preview_url çağırın; araç bu tek bağlantı noktasını idempotent olarak yayınlar ve döndürülen bağlantı noktası modunu kullanarak temiz bir genel URL veya süresi dolan özel imzalı URL döndürür. Özel bağlantılar varsayılan olarak bir saattir; expires_in_seconds değerini 1 ile 604800 saniye arasında ayarlayın. Önizleme URL'leri bölümüne bakın.

Bilgisayar kullanımı

sandbox_computer, superserve/desktop gibi bir masaüstü şablonundan oluşturulan bir sandbox'ta GUI masaüstünü yönlendirir. Çağrı başına bir action alır ve bilgisayar kullanımı modellerinin yaydığı sözcük dağarcığında: 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 ve stream_url. İşaretçi eylemleri coordinate: [x, y] ekran pikseli cinsinden alır (başlangıç sol üst); key ve type text alır; scroll scroll_direction ve isteğe bağlı bir scroll_amount alır.

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

Girdi eylemleri sonucun taze bir ekran görüntüsünü döndürür; böylece modelin eylem-sonra-bak turu tek bir araç çağrısıdır; arka arkaya birkaç eylem gönderirken screenshot_after: false iletin. wait, sandbox'a istek olmadan duration_ms (en fazla 10 saniye) bekler. stream_url, sandbox'ın önizleme politikası altında masaüstü için canlı bir tarayıcı görüntüleyicisi döndürür.

Bir girdi eylemi başarısız olursa, girdi zaten iletilmiş olabilir. Araç bunu söyler ve tekrarlamadan önce ajandan ekran görüntüsü almasını ister. Temel SDK yüzeyi için Masaüstü kılavuzuna bakın.

Henüz MCP yüzeyinde yok

MCP sunucusu, yaygın aracı döngüsünü kapsar; yukarıdaki tablo, tam v1 araç setidir. Birkaç SDK yeteneği henüz açığa çıkarılmamıştır — bunlar için doğrudan TypeScript SDK kullanın:

• Gizli anahtar oluşturma — Secret.create() (MCP sunucusu yalnızca mevcut gizli anahtarları bağlar).
• Akış ve etkileşimli komutlar — akış run() geri çağrıları ve commands.spawn (stdin, sinyaller, uzun süreli süreçler).
• Büyük veya akış aktarımları — dizin indirme, sandbox_files_download_dir aracılığıyla 10 MiB'a kadar desteklenir; bunun ötesinde (ve arşiv/akış yüklemeleri veya 1 MiB okuma / 8 MiB satır içi yazma sınırlarını aşan tek dosyalar için), SDK/CLI kullanın (files.downloadDir, akış yükleme).
• Faturalandırma ve sağlayıcı keşfi — kullanım verileri ve gizli sağlayıcı kurulumu için Provider.list().

Bunlar takip edilecek öğeler olarak kaydedilmiştir.

Nasıl çalışır

Sunucu, TypeScript SDK sarmalar ve yalnızca kontrol düzlemi SUPERSERVE_API_KEY değerini tutar. Her araç çağrısı, hedef sandbox'a kimlikle bağlanır; SDK, sandbox başına veri düzlemi erişim belirtecini dahili olarak yönetir ve devam ettirmede döndürür, bu nedenle modele veya araç çıktısına asla açığa çıkmaz. Araçlar durumsuzdur — gizli bir "geçerli sandbox" yoktur — bu, çok turlu ve paralel araç çağrılarında davranışı öngörülebilir kılar.

Sorun giderme

• Araçlar görünmüyor veya sunucu başlatılamıyor. Neden neredeyse her zaman API anahtarıdır — MCP istemcileri, ortam değişkenlerini kabuğunuzdan devralmaz. SUPERSERVE_API_KEY değerini sunucunun env bloğuna ayarlayın (bkz. Kurulum), yalnızca terminalinize değil.
• Authentication failed. Anahtar eksik veya geçersiz. Üretim anahtarları ss_live_ ile başlar; API anahtarı sayfasında bir tane oluşturun.
• İlk çağrı yavaş. npx paketi ilk kullanımda indirir ve önbelleğe alır; sonraki başlatmalar hızlıdır.
• Node 18+ gerektirir. Yerel sunucu, Node üzerinde npx aracılığıyla çalışır. (Barındırılan uç noktasının yerel çalışma zamanı gereksinimi yoktur.)
• Barındırılan uç noktadan 401 Unauthorized. Taşıyıcı belirteç eksik veya geçerli bir ss_live_ anahtarı değil. Bunu Authorization: Bearer ss_live_… olarak gönderin (bkz. Barındırılan).

İlgili

Sandbox'ları duraklatın, devam ettirin ve silin. Exec, akış, cwd, env ve zaman aşımları. Sağlayıcı anahtarlarını sandbox'a açığa çıkarmadan aracılık edin. MCP sunucusunun sarmaladığı kitaplık.

Bu dokümantasyon, bir geliştirici dokümantasyon platformu olan Mintlify üzerinde oluşturulmuş ve barındırılmıştır.