Superserve Sandbox MCP

MCP Sunucusu

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

Superserve MCP sunucusu (@superserve/mcp), sanal alan temel öğelerini Model Bağlam Protokolü araçları olarak sunar, böylece MCP özellikli herhangi bir istemci — Claude, Cursor, VS Code, Windsurf, Codex — yalıtılmış bir Firecracker mikroVM'de sanal alanlar oluşturabilir, komutlar çalıştırabilir, dosya okuyup yazabilir, şablonlar oluşturabilir, gizli bilgileri aracılık edebilir ve ağ erişimini kontrol edebilir.

İki şekilde çalıştırın: npx aracılığıyla stdio üzerinden yerel olarak veya yerel kurulum gerektirmeden https://mcp.superserve.ai adresindeki barındırılan uç noktaya karşı. Her ikisi de SUPERSERVE_API_KEY anahtarınızla kimlik doğrulaması yapar ve çağrı başına kimliğe göre bir sanal alanı hedefler. TypeScript SDK üzerine ince bir sarmalayıcıdır, bu nedenle sanal alan başına veri düzlemi belirteci modele asla ulaşmaz.

Hızlı Başlangıç

Sunucuyu istemcinize ekleyin (bkz. Kurulum), ardından ajana "bir sanal alan oluştur ve içinde python --version çalıştır" deyin. Ajan sandbox_create ve ardından sandbox_exec çağrısı yapar ve sonucu bildirir — sizden kod yazmanız gerekmez.

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

Kurulum

Sunucunun `env` ayarında `SUPERSERVE_API_KEY` değerini ayarlayın — MCP istemcileri bunu kabuğunuzdan devralmaz. İstemcinizin desteklediği yerlerde 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 anahtarı 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` dosyasını 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 Akışkan HTTP konuşur — npx yok, Node yok. Superserve API anahtarınızı bir taşıyıcı belirteç olarak gönderin. Uç nokta durumsuzdur ve hesap kapsamlıdır (anahtarınız zaten ekibinizle eşleşir) ve sanal alan başına veri düzlemi belirteci sunucudan asla ayrılmaz.

Taşıyıcı kimlik doğrulaması, bir 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 bunu henüz desteklemez — orada [yerel](#install) 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 anahtarı 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, aktarım 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 sanal alan oluşturur; id değerini döndürür. Hemen aktif ve hazır. secrets ve çıkış kurallarını kabul eder.
sandbox_update	Oluşturulduktan sonra bir sanal alanın meta verilerini veya çıkış (allow_out/deny_out) kurallarını değiştirir.
sandbox_list	Sanal alanlarınızı (aktif ve duraklatılmış) listeler, meta verilere göre filtrelenebilir.
sandbox_info	Bir sanal alanın durumunu, kaynaklarını, meta verilerini, ağ kurallarını ve gizli 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 sanal alanı otomatik olarak devam ettirir.
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şiklik zamanı).
sandbox_files_download_dir	Bir dizini base64 ZIP olarak indirir (sembolik bağlar atlanır). 10 MiB ile sınırlıdır; daha büyük → SDK/CLI.
sandbox_pause	Bir sanal alanı duraklatır; durum korunur.
sandbox_resume	Duraklatılmış bir sanal alanı devam ettirir (genellikle gereksizdir — exec otomatik olarak devam ettirir).
sandbox_kill	Bir sanal alanı kalıcı olarak siler.
sandbox_preview_url	Dinleyen bir bağlantı noktası için genel URL'yi oluşturur (kimlik doğrulamasız — o bağlantı noktasındaki her şey internete açıktır).
sandbox_network_log	Bir sanal alanın giden bağlantılarını denetler (ana bilgisayar, karar, bayt). Duraklatılmış bir sanal alanı otomatik olarak devam ettirir.
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 (eşzamansız — hazır olana kadar yoklayın).
secret_list	Bağlanabilir ekip gizli bilgilerini listeler (yalnızca meta veri — asla değerler).
sandbox_attach_secret	Depolanmış bir gizli bilgiyi, bir ortam değişkeni altında çalışan bir sanal alana bağlar.
sandbox_detach_secret	Bir sanal alandan bir gizli bağlamayı 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 araçlarıdır. Bir kimlik almak için bunlardan biriyle başlayı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_preview_url, sandbox_template_list, secret_list), istemcilerin onay istemlerini atlayabilmesi için açıklanmıştır; sandbox_kill yıkıcı olarak açıklanmıştır.

Örnek

"bir sanal alan oluştur, 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: "" }

İşi bittiğinde, ajan sandbox_pause (durum korunur, saklaması daha ucuz) 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ıl (varsayılan: https://api.superserve.ai).

Davranış ve sınırlamalar

• Otomatik devam ettirme. sandbox_exec ve dosya araçları, duraklatılmış bir sanal alanı şeffaf bir şekilde devam ettirir, böylece ajanların asla önce sandbox_resume çağırması gerekmez. sandbox_resume yalnızca bir sanal alanı 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 olacak şekilde keser — kesilmiş 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 tüm dosyayı SDK/CLI ile 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, maksimum 10 dakika ile sınırlıdır. timeout_ms ile çağrı başına geçersiz kılın.
• Çıkış kontrol edilebilir. allow_out (alan adı desenleri veya CIDR'ler) izin verilen hedefleri ekler; deny_out (yalnızca CIDR'ler) bunları engeller. allow_out tek başına bir sanal alanı kilitlemez — katı bir izin listesi için, bunu 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 sanal alanı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 bundan sonra ne yapacağını söyleyen kısa bir mesaj döndürür — örn. "Sanal alan kotasına ulaşıldı. Bir sanal alanı duraklatın veya sonlandırın ya da daha sonra tekrar deneyin." — ham yığın izlemesi yerine, böylece ajan kendi kendini düzeltebilir.

Gizli bilgiler, şablonlar ve bağlantı noktaları

Gizli bilgiler. Kimlik bilgilerini düz metin env_vars olarak iletmeyin. Bunun yerine:

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

Sanal alan bir proxy belirteci görür; platform, gerçek kimlik bilgisini yalnızca gizli bilginin izin verilen ana bilgisayarlarına yapılan giden istekler için değiştirir.

Şablonlar. Bir sanal alan, vCPU/bellek/disk özelliklerini şablonundan devralır ve sandbox_create zamanında bunları geçersiz kılamaz. Belirli bir şekil (diyelim ki 4 vCPU'lu bir sanal alan) veya önceden yüklenmiş yazılım elde etmek için, sandbox_template_create ile bir şablon oluşturun, ardından status durumu ready olana kadar sandbox_template_list ile yoklayın ve from_template olarak iletin.

Bağlantı noktaları. Sanal alanda bir sunucu başlatın (sandbox_exec, örn. python3 -m http.server 8000), ardından genel URL'sini almak için sandbox_preview_url çağrısı yapın. Bir bağlantı noktasına bağlı herhangi bir işleme https://{port}-{id}.sandbox.superserve.ai adresinden kimlik doğrulaması olmadan erişilebilir — yalnızca genel olmasını amaçladığınız bağlantı noktalarını açığa çıkarı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 yeteneği henüz açığa çıkarılmamıştır — doğrudan TypeScript SDK için şunlara başvurun:

• Gizli bilgi oluşturma — Secret.create() (MCP sunucusu yalnızca mevcut gizli bilgileri bağlar).
• Akış ve etkileşimli komutlar — run() geri çağrılarını ve commands.spawn (stdin, sinyaller, uzun süreli işlemler) akışı.
• Büyük veya akış aktarımları — sandbox_files_download_dir aracılığıyla 10 MiB'a kadar dizin indirme 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 bilgi sağlayıcı kurulumu için Provider.list().

Bunlar takip edilecek konular olarak izlenmektedir.

Nasıl çalışır

Sunucu, TypeScript SDK'sini sarar ve yalnızca kontrol düzlemi SUPERSERVE_API_KEY'inizi tutar. Her araç çağrısı, hedef sanal alana kimlikle bağlanır; SDK, sanal alan başına veri düzlemi erişim belirtecini dahili olarak yönetir ve devam ettirmede döndürür, böylece modele hiçbir zaman gösterilmez veya araç çıktısında döndürülmez. Araçlar durumsuzdur — gizli bir "geçerli sanal alan" yoktur — bu da ç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'i yalnızca terminalinizde değil, sunucunun env bloğunda ayarlayın (bkz. Kurulum).
• Authentication failed. Anahtar eksik veya geçersiz. Üretim anahtarları ss_live_ ile başlar; API anahtarı sayfasından 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ç noktanı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

Sanal alanları duraklatın, devam ettirin ve silin. Çalıştırma, akış, cwd, env ve zaman aşımları. Aracı sağlayıcı anahtarlarını sanal alana göstermeden yönetin. MCP sunucusunun sardığı kütüphane.