Superserve Sandbox MCP

официальный

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

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

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

Создание и запуск песочниц — Попросите ассистента создать песочницу и выполнить команды, например python --version, с помощью sandbox_create и sandbox_exec.
Управление файлами в песочницах — Попросите ассистента читать, записывать или выводить список файлов внутри песочницы с помощью sandbox_files_read, sandbox_files_write и sandbox_files_list.
Контроль сетевого доступа — Настройте правила исходящего трафика в sandbox_create или sandbox_update, чтобы разрешить или заблокировать внешние адреса, затем проверяйте трафик с помощью sandbox_network_log.
Публикация предпросмотра URL — Попросите ассистента открыть доступ к запущенному сервису, вызвав sandbox_preview_url, чтобы получить публичную или временную приватную ссылку.
Управление графическим рабочим столом — Используйте sandbox_computer для создания скриншотов, кликов, ввода текста или прокрутки в песочнице с рабочим столом для задач автоматизации браузера.
Управление жизненным циклом песочницы — Приостанавливайте, возобновляйте или полностью удаляйте песочницы с помощью sandbox_pause, sandbox_resume и sandbox_kill.

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

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 или истекающую приватную подписанную ссылку.
`sandbox_network_log`	Аудирует исходящие соединения песочницы (хост, вердикт, байты) без её возобновления.
`sandbox_computer`	Управляет GUI-песочницей с рабочим столом: скриншот, мышь, клавиатура, прокрутка, изменение размера, URL просмотра. Одно действие за вызов.
`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 (шаблоны доменов, IP или CIDR) добавляет разрешённые назначения; deny_out (IP или CIDR, без доменов) блокирует их. Один allow_out не изолирует песочницу полностью — для строгого белого списка объедините его с deny_out: ["0.0.0.0/0"] (запретить всё, затем разрешить перечисленные назначения). Если в белом списке есть доменные правила или рабочая нагрузка резолвит имена хостов, также разрешите DNS-резолверы песочницы, 1.1.1.1/32 и 8.8.8.8/32, поскольку запрет всего блокирует и DNS; не включайте их в белый список только с IP, где разрешённый резолвер — лишь лишний исходящий канал. Задавайте их на 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, либо истекающую приватную подписанную ссылку. Приватные ссылки по умолчанию действуют один час; установите expires_in_seconds в значение от 1 до 604800 секунд. См. URL предпросмотра.

Компьютерное использование

sandbox_computer управляет GUI-рабочим столом в песочнице, созданной из шаблона рабочего стола, такого как superserve/desktop. Принимает одно action за вызов в словаре, который выдают модели компьютерного использования: 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 и stream_url. Действия указателя принимают coordinate: [x, y] в пикселях экрана (начало координат — верхний левый угол); key и type принимают text; scroll принимает scroll_direction и необязательный scroll_amount.

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

Действия ввода возвращают свежий скриншот результата, поэтому цикл "действие-затем-взгляд" модели — это один вызов инструмента; передайте screenshot_after: false, когда отправляете несколько действий подряд. wait делает паузу на duration_ms (максимум 10 секунд) без запроса к песочнице. stream_url возвращает живой браузерный просмотрщик для рабочего стола в рамках политики предпросмотра песочницы.

Если действие ввода не удалось, ввод мог уже быть доставлен. Инструмент сообщает об этом и просит агента сделать скриншот перед повтором. См. Руководство по рабочему столу для базовой поверхности SDK.

Пока не в 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-сервер.

Эта документация создана и размещена на Mintlify, платформе документации для разработчиков.