Superserve Sandbox MCP

официальный

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

Смотреть на superserve.ai

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

Создайте изолированную песочницу — попросите ассистента запустить Firecracker microVM с помощью sandbox_create, при необходимости добавив секреты и правила исходящего трафика.
Выполняйте команды оболочки внутри песочницы — запускайте команды через sandbox_exec и получайте stdout, stderr и код возврата (автоматически возобновляет приостановленные песочницы).
Читайте и записывайте файлы в песочнице — используйте sandbox_files_read и sandbox_files_write для просмотра или размещения файлов с автоматическим созданием родительских каталогов.
Откройте публичный доступ к песочнице — запустите серверный процесс и вызовите sandbox_preview_url, чтобы получить общедоступный URL для прослушиваемого порта.
Аудируйте исходящий сетевой трафик — проверьте, с какими хостами взаимодействовала песочница и были ли они разрешены или заблокированы, с помощью sandbox_network_log.
Создавайте и управляйте пользовательскими шаблонами — создайте шаблон с определенными vCPU/памятью/диском или предустановленным ПО с помощью sandbox_template_create, затем запускайте из него песочницы.

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

MCP-сервер

Создавайте, запускайте и управляйте изолированными средами Superserve из любого 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), что облачная конечная точка пока не поддерживает — в этих случаях используйте [локальную](#install) установку. ```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` и правила выхода.
`sandbox_update`	Изменить метаданные или правила выхода (`allow_out`/`deny_out`) изолированной среды после создания.
`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 для прослушиваемого порта (без аутентификации — всё, что на этом порту, доступно из интернета).
`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_preview_url, sandbox_template_list, secret_list) помечены, чтобы клиенты могли пропускать запросы подтверждения; 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.

Порты. Запустите сервер в изолированной среде (sandbox_exec, например, python3 -m http.server 8000), затем вызовите sandbox_preview_url, чтобы получить его публичный URL. Любой процесс, привязанный к порту, доступен по адресу https://{port}-{id}.sandbox.superserve.ai без аутентификации — открывайте только те порты, которые должны быть публичными.

Пока не в интерфейсе 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. Каждый вызов инструмента подключается к целевой песочнице по идентификатору; SDK управляет токеном доступа к плоскости данных для каждой песочницы внутренне и обновляет его при возобновлении, поэтому он никогда не раскрывается модели и не возвращается в выводе инструментов. Инструменты не имеют состояния — отсутствует скрытая «текущая песочница» — что обеспечивает предсказуемое поведение при многошаговых и параллельных вызовах инструментов.

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

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

Связанные материалы

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