Superserve Sandbox MCP

официальный

Безопасные виртуальные машины для агентов, размещённые Superserve

Смотреть на superserve.aiПопробовать этот MCPСпонсировано

Что можно делать с Superserve Sandbox MCP?

Create and run sandboxes — Ask your assistant to spin up a sandbox with sandbox_create and execute commands like python --version via sandbox_exec.
Manage files in sandboxes — Use sandbox_files_write, sandbox_files_read, and sandbox_files_list to create, view, or organize files inside a sandbox.
Control sandbox lifecycle — Pause, resume, or permanently delete sandboxes with sandbox_pause, sandbox_resume, and sandbox_kill to manage resources.
Publish preview URLs — Expose a running service by calling sandbox_preview_url to get a public or expiring private link.
Bind secrets securely — Attach or detach stored team secrets to sandboxes via sandbox_attach_secret and sandbox_detach_secret without exposing raw values.
Build custom templates — Create reusable sandbox templates with specific CPU/memory/disk shapes using sandbox_template_create and list them with sandbox_template_list.

Документация

MCP-сервер

Создавайте, запускайте и управляйте песочницами Superserve из любого MCP-клиента.

Хотите, чтобы агент сам создавал песочницы? Этот MCP-сервер именно это и делает.

MCP-сервер Superserve (@superserve/mcp) предоставляет примитивы песочниц как инструменты Model Context Protocol, поэтому любой MCP-совместимый клиент — Claude, Cursor, VS Code, Windsurf, Codex — может создавать песочницы, выполнять команды, читать и записывать файлы, собирать шаблоны, управлять секретами и контролировать сетевой доступ в изолированной микро-ВМ Firecracker.

Запускается двумя способами: локально через stdio с помощью npx, или через хостируемую конечную точку на https://mcp.superserve.ai без локальной установки. Оба способа аутентифицируются с помощью вашего SUPERSERVE_API_KEY и нацелены на песочницу по ID в каждом вызове. Это тонкая обёртка над TypeScript SDK, поэтому токен плоскости данных для каждой песочницы никогда не достигает модели.

Быстрый старт

Добавьте сервер в свой клиент (см. Установка), затем попросите агента "создать песочницу и запустить в ней python --version". Агент вызывает sandbox_create, затем sandbox_exec и сообщает результат — без единой строчки кода с вашей стороны.

Вам понадобится API-ключ Superserve — создайте его на странице API-ключи. Глобальной установки нет; npx загружает сервер при первом использовании.

Установка

Примечание

Установите SUPERSERVE_API_KEY в env сервера — MCP-клиенты не наследуют его из вашей оболочки. Предпочитайте запрос секретного ввода вместо вставки сырого ключа там, где ваш клиент это поддерживает (см. VS Code ниже).

```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` (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` (проект) или `~/.cursor/mcp.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" }
    }
  }
}
```

Добавьте в `.vscode/mcp.json`. Блок `inputs` запрашивает ключ вместо хранения его в открытом виде:

```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`:

```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`. `env_vars` передаёт `SUPERSERVE_API_KEY` из вашего окружения, поэтому сырой ключ не хранится в файле конфигурации (сначала экспортируйте его в оболочке). Codex также читает `instructions` сервера для руководства по кросс-инструментальным рабочим процессам.

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

Для [хостируемой](#hosted-remote) конечной точки используйте `url = "https://mcp.superserve.ai"` с `bearer_token_env_var = "SUPERSERVE_API_KEY"`.

Хостируемая (удалённая)

Не хотите ничего запускать локально? Хостируемая конечная точка на https://mcp.superserve.ai говорит по Streamable HTTP — без npx, без Node. Отправляйте ваш API-ключ Superserve как bearer-токен. Конечная точка не сохраняет состояние и привязана к аккаунту (ваш ключ уже сопоставлен с вашей командой), а токен плоскости данных для каждой песочницы никогда не покидает сервер.

Примечание

Bearer-аутентификация работает в любом клиенте, где можно задать заголовок запроса — Claude Code, Cursor, VS Code и коннектор Anthropic Messages API. Claude.ai, пользовательский интерфейс Custom Connector в Claude Desktop и режим разработчика ChatGPT не предлагают поле статического bearer / пользовательского заголовка (они ожидают OAuth), который хостируемая конечная точка пока не поддерживает — используйте локальную установку там.

```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` (проект) или `~/.cursor/mcp.json` (глобально):

```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`. Блок `inputs` запрашивает ключ вместо хранения его в открытом виде:

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

Передайте его как коннектор в запросе [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"
    }
  ]
}
```

Те же инструменты и поведение, что и у локального сервера — единственное отличие в транспорте и в том, что ключ передаётся как bearer-заголовок вместо переменной env.

Инструменты

Инструмент	Что делает
`sandbox_create`	Создаёт новую песочницу; возвращает её `id`. Принимает `secrets`, правила исходящего трафика и `preview_access`.
`sandbox_update`	Изменяет метаданные, правила исходящего трафика, окна жизненного цикла или `preview_access`.
`sandbox_list`	Перечисляет ваши песочницы (активные и приостановленные), фильтруемые по метаданным.
`sandbox_info`	Получает статус, ресурсы, метаданные, сетевые правила и привязки секретов одной песочницы. Только чтение.
`sandbox_exec`	Выполняет команду оболочки; возвращает stdout, stderr, код выхода. Автоматически возобновляет приостановленную песочницу.
`sandbox_files_read`	Читает файл (текст UTF-8 или base64 для бинарных).
`sandbox_files_write`	Создаёт или перезаписывает файл. Родительские каталоги создаются автоматически.
`sandbox_files_list`	Перечисляет записи каталога (имя, тип, размер, время изменения).
`sandbox_files_download_dir`	Скачивает каталог как ZIP в base64 (символические ссылки пропускаются). Ограничение 10 МиБ; больше — SDK/CLI.
`sandbox_pause`	Приостанавливает песочницу; состояние сохраняется.
`sandbox_resume`	Возобновляет приостановленную песочницу (обычно не нужно — exec возобновляет автоматически).
`sandbox_kill`	Окончательно удаляет песочницу.
`sandbox_preview_url`	Публикует порт и возвращает чистый публичный URL или истекающий приватный подписанный URL.
`sandbox_network_log`	Аудирует исходящие соединения песочницы (хост, вердикт, байты) без её возобновления.
`sandbox_template_list`	Перечисляет шаблоны (базовые образы), из которых ваша команда может запускать песочницы.
`sandbox_template_create`	Собирает пользовательский шаблон с конкретной формой vCPU/память/диск или предустановленным ПО (асинхронно — опрашивайте готовность).
`secret_list`	Перечисляет привязываемые секреты команды (только метаданные — никогда значения).
`sandbox_attach_secret`	Привязывает сохранённый секрет к запущенной песочнице под переменную окружения.
`sandbox_detach_secret`	Удаляет привязку секрета из песочницы.

Большинство инструментов принимают sandbox_id; исключения — sandbox_create, sandbox_list, sandbox_template_list, sandbox_template_create и secret_list. Начните с одного из них, чтобы получить ID, затем передавайте его в последующие вызовы. Инструменты только для чтения (sandbox_list, sandbox_info, sandbox_files_read, sandbox_files_list, sandbox_files_download_dir, sandbox_network_log, sandbox_template_list, secret_list) помечены так, чтобы клиенты пропускали запросы подтверждения; sandbox_preview_url — идемпотентная запись, поскольку публикует запрошенный порт, а sandbox_kill помечен как разрушительный.

Пример

Типичный поток агента для "подними песочницу, напиши Python-скрипт, выводящий первые простые числа, и запусти его":

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

Когда готово, агент может sandbox_pause (состояние сохраняется, дешевле держать) или sandbox_kill (окончательно).

Конфигурация

Переменная	Обязательна	Описание
`SUPERSERVE_API_KEY`	Да	Ваш API-ключ Superserve (начинается с `ss_live_`).
`SUPERSERVE_BASE_URL`	Нет	Переопределяет URL плоскости управления (по умолчанию `https://api.superserve.ai`).

Поведение и ограничения

Автовозобновление. sandbox_exec и файловые инструменты прозрачно возобновляют приостановленную песочницу, поэтому агентам никогда не нужно вызывать sandbox_resume первым. sandbox_resume существует только для явного прогрева песочницы.
Вывод ограничен для контекста. sandbox_exec усекает stdout и stderr до 32 КиБ каждый — усечённый результат устанавливает truncated: true и сообщает исходную длину в байтах. sandbox_files_read отклоняет файлы больше 1 МиБ (не возвращает частичное содержимое); ошибка говорит прочитать срез с помощью sandbox_exec (например, head -c) или скачать весь файл через SDK/CLI. Встроенное содержимое sandbox_files_write ограничено 8 МиБ.
Таймаут команды по умолчанию — 60 секунд, максимум 10 минут. Переопределяйте его в каждом вызове через timeout_ms.
Исходящий трафик управляем. allow_out (шаблоны доменов или CIDR) добавляет разрешённые назначения; deny_out (только CIDR) блокирует их. Один allow_out не изолирует песочницу полностью — для строгого белого списка комбинируйте его с deny_out: ["0.0.0.0/0"] (запретить всё, затем разрешить перечисленные назначения). Задавайте их на sandbox_create или sandbox_update и аудируйте, чего песочница реально достигла, через sandbox_network_log.
Ошибки действенны. Неудачный вызов инструмента возвращает короткое сообщение, говорящее агенту, что делать дальше — например, "Достигнута квота песочниц. Приостановите или завершите песочницу, либо повторите позже." — вместо сырого стектрейса, чтобы агент мог сам исправиться.

Секреты, шаблоны и порты

Секреты. Не передавайте учётные данные как открытый текст в env_vars. Вместо этого:

Создайте секрет один раз с помощью TypeScript SDK (Secret.create()) или консоли — сырое значение никогда не проходит через агента или MCP-сервер, поэтому создание секретов намеренно не является MCP-инструментом.
Обнаруживайте привязываемые секреты через secret_list (только метаданные — значения никогда не покидают платформу).
Привязывайте при создании — secrets: { ANTHROPIC_API_KEY: "anthropic-prod" } на sandbox_create — или позже через sandbox_attach_secret / sandbox_detach_secret.

Песочница видит прокси-токен; платформа подставляет реальные учётные данные только для исходящих запросов к разрешённым хостам секрета.

Шаблоны. Песочница наследует vCPU/память/диск от своего шаблона и не может их переопределить при sandbox_create. Чтобы получить конкретную форму (например, песочницу с 4 vCPU) или предустановленное ПО, соберите шаблон через sandbox_template_create, затем опрашивайте sandbox_template_list, пока его status не станет ready, прежде чем передавать его как from_template.

Порты. Новые MCP-песочницы используют public как доступ по умолчанию для вновь публикуемых портов; достижимы только явно опубликованные порты. Передайте preview_access: "private" в sandbox_create (или sandbox_update), чтобы изменить значение по умолчанию для будущих портов. Существующие порты сохраняют свой режим. Запустите сервер с sandbox_exec, затем вызовите sandbox_preview_url; инструмент идемпотентно публикует этот один порт и использует возвращённый режим порта, чтобы вернуть либо чистый публичный URL, либо истекающий приватный подписанный URL. Приватные ссылки по умолчанию действуют один час; установите expires_in_seconds значением от 1 до 604800 секунд. См. URL предпросмотра.

Пока не в MCP-поверхности

MCP-сервер покрывает общий цикл агента; таблица выше — полный набор инструментов v1. Некоторые возможности SDK пока не раскрыты — обращайтесь напрямую к TypeScript SDK для:

Создание секретов — Secret.create() (MCP-сервер только привязывает существующие секреты).
Потоковые и интерактивные команды — потоковые run() обратные вызовы и commands.spawn (stdin, сигналы, длительные процессы).
Большие или потоковые передачи — загрузка каталога поддерживается до 10 МиБ через sandbox_files_download_dir; сверх этого (а также для архивных/потоковых загрузок или отдельных файлов, превышающих лимиты чтения 1 МиБ / встроенной записи 8 МиБ) используйте SDK/CLI (files.downloadDir, потоковая загрузка).
Биллинг и обнаружение провайдеров — данные об использовании и Provider.list() для настройки секрет-провайдеров.

Они отслеживаются как последующие задачи.

Как это работает

Сервер оборачивает TypeScript SDK и хранит только ваш SUPERSERVE_API_KEY плоскости управления. Каждый вызов инструмента подключается к целевому песочнице по ID; SDK управляет токеном доступа к плоскости данных для каждой песочницы внутри и ротирует его при возобновлении, поэтому он никогда не раскрывается модели и не возвращается в выводе инструментов. Инструменты не имеют состояния — нет скрытой «текущей песочницы», — что обеспечивает предсказуемое поведение при многоходовых и параллельных вызовах инструментов.

Устранение неполадок

Инструменты не отображаются, или сервер не запускается. Почти всегда причина в ключе API — MCP-клиенты не наследуют переменные окружения из вашей оболочки. Установите SUPERSERVE_API_KEY в блоке env сервера (см. Установка), а не только в терминале.
Authentication failed. Ключ отсутствует или недействителен. Продакшн-ключи начинаются с ss_live_; создайте его на странице API-ключ.
Первый вызов медленный. npx загружает пакет при первом использовании и кэширует его; последующие запуски быстрые.
Требуется Node 18+. Локальный сервер работает на Node через npx. (Хостируемая конечная точка не требует локальной среды выполнения.)
401 Unauthorized от хостируемой конечной точки. Bearer-токен отсутствует или не является действительным ключом ss_live_. Отправьте его как Authorization: Bearer ss_live_… (см. Хостируемая).

Связанное

Пауза, возобновление и удаление песочниц. Exec, потоковая передача, cwd, env и тайм-ауты. Брокерские ключи провайдеров без их раскрытия песочнице. Библиотека, которую оборачивает MCP-сервер.