Superserve Sandbox MCP

MCP Sunucusu

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

Ajanın kendisinin 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 destekleyen 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 https://mcp.superserve.ai adresindeki barındırılan uç noktaya karşı yerel kurulum olmadan. 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 (Kurulum bölümüne bakın), 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ında 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 yok, Node yok. 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 ise 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ık 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ğerini 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 ve çıkış kodunu döndürür. Duraklatılmış bir sandbox'ı otomatik 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_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 kimlik güçlü 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).

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.
• Bağlam için çıktı sınırlıdı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çeriği 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 veya CIDR'ler) izin verilen hedefler ekler; deny_out (yalnızca CIDR'ler) 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). 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 platformdan asla çı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'lu bir 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 modlarını korur. Sunucuyu sandbox_exec ile başlatın, ardından sandbox_preview_url çağırın; araç o tek bağlantı noktasını kimlik güçlü bir şekilde 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 bir değere ayarlayın. Önizleme URL'leri bölümüne bakın.

Henüz MCP yüzeyinde olmayanlar

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

• Sır oluşturma — Secret.create() (MCP sunucusu yalnızca mevcut sırları bağlar).
• Akış ve etkileşimli komutlar — run() geri çağrılarını ve commands.spawn (stdin, sinyaller, uzun süreli süreçler) akışını sağlar.
• 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 sır sağlayıcı kurulumu için Provider.list().

Bunlar takip edilecek konular olarak işaretlenmiştir.

Nasıl çalışır

Sunucu, TypeScript SDK sarmalar ve yalnızca kontrol düzlemi SUPERSERVE_API_KEY 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 ettirildiğinde döndürür, bu nedenle modele asla açığa çıkmaz veya araç çıktısında döndürülmez. 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. API anahtarı neredeyse her zaman nedendir — MCP istemcileri, kabuğunuzdaki ortam değişkenlerini 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, npx aracılığıyla Node üzerinde ç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. 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.