# Инструменты MCP управления платформой

API-шлюз Just Run публикует сервер Model Context Protocol уровня аккаунта по адресу:

```
https://your-just-run-host/mcp
```

Он использует способ передачи MCP Streamable HTTP с сохранением состояния и объявляет возможность `tools`. Это управляющая часть платформы: через этот сервер клиенты управляют песочницами и связанными сущностями. Не путайте его с Hosted MCP, где Just Run запускает выбранный или предоставленный вами MCP-сервер; инструменты `hosted_mcp_*` управляют такими инстансами.

## Аутентификация[​](#authentication "Прямая ссылка на Аутентификация")

OAuth-клиенты управляют bearer-токенами автоматически. Для подключения по персональному токену отправляйте этот заголовок в каждом HTTP-запросе:

```
Authorization: Bearer your-personal-access-token
```

Для постоянной конфигурации клиента используйте [персональный токен](/accounts/personal-access-tokens.md):

* `read_only` объявляет и разрешает только инструменты чтения;
* `full` объявляет и разрешает инструменты чтения и записи.

Ограничение на запись применяется дважды. Для токена `read_only` ответ `tools/list` не содержит инструментов записи, а прямой `tools/call` такого инструмента отклоняется до начала серверной операции. Неизвестные будущие инструменты считаются инструментами записи, пока не будут явно проверены.

Отсутствующий, некорректный, просроченный, отозванный или неверный bearer-токен получает HTTP `401` до обработки MCP-сообщения.

### OAuth[​](#oauth "Прямая ссылка на OAuth")

OAuth включен по умолчанию для вошедших пользователей. Каждое подключение требует согласия в браузере и действующих прав выбранного аккаунта. Поддерживаются только права `full`. Запрос аутентификации Bearer при `401` объявляет метаданные защищенного ресурса; метаданные сервера авторизации описывают поток с кодом авторизации и PKCE (S256). Оператор может явно отключить OAuth или ограничить пользователей.

Клиенты представляются через Client ID Metadata Documents (CIMD): `client_id` — HTTPS-адрес JSON-документа с именем клиента и адресами его обратного вызова, регистрация не нужна. Claude Code и Codex поддерживают CIMD — добавьте адрес сервера без заголовка с персональным токеном и войдите. Динамическая регистрация клиентов не поддерживается: клиент без CIMD подключается по персональному токену. Страница согласия показывает имя клиента вместе с хостом его документа и предупреждает о хостах, которые Just Run не знает.

Подключение работает в аккаунте, активном в Just Run в момент согласия: страница согласия показывает этот аккаунт. Подключение продлевается, пока клиент им пользуется: истекает после 30 дней без использования и не позже чем через 90 дней после согласия. Токен доступа истекает через 10 минут; клиент обновляет его с ротацией токена обновления. Просмотреть и отозвать подключения можно на вкладке *MCP-подключения* страницы *Токены доступа* (`/tokens`). Отзыв блокирует токены доступа и обновления; созданные клиентом ресурсы продолжают работать.

Учетные данные доступа OAuth работают только на эндпоинте `/mcp` управления платформой. Они не заменяют персональный токен для REST и SDK, не авторизуют вспомогательные скрипты навыков ассистентов, работающие через REST, и не подходят для URL инстанса Hosted MCP. Храните учетные данные в MCP-клиенте. Подключения по персональному токену, описанные ниже, тоже поддерживаются.

MCP-сессия привязана к пользователю, аккаунту, правам и учетным данным или OAuth-подключению. Другой персональный токен или другое OAuth-подключение не может использовать ее ID; обновление токена внутри того же OAuth-подключения сохраняет привязку. После отказа из-за устаревшей сессии повторите `initialize`.

## Подключение[​](#connect "Прямая ссылка на Подключение")

Для подключения по персональному токену настройте MCP-клиент:

| Параметр        | Значение                         |
| --------------- | -------------------------------- |
| Способ передачи | Streamable HTTP                  |
| URL             | `https://your-just-run-host/mcp` |
| Заголовок       | `Authorization: Bearer <PAT>`    |

Используйте реализацию Streamable HTTP, а не отправляйте изолированные JSON-RPC-запросы. Клиент отвечает за handshake `initialize`, согласованную версию протокола, `Mcp-Session-Id` в следующих запросах и поддержку ответов `application/json` или `text/event-stream`. Сессия восстанавливается между инстансами шлюза, но после сообщения об устаревшей сессии клиенту все равно нужно повторить `initialize`.

Успешное подключение сообщает имя сервера `just-run`. После подключения вызовите `tools/list` и считайте полученный `inputSchema` канонической схемой текущей инсталляции.

## Инструменты чтения[​](#read-tools "Прямая ссылка на Инструменты чтения")

Инструменты чтения объявляются для персональных токенов `read_only` и `full` и OAuth-подключений с правами `full`.

### Песочницы и часть платформы для работы с их данными[​](#sandboxes-and-their-data-plane "Прямая ссылка на Песочницы и часть платформы для работы с их данными")

| Инструмент     | Основные аргументы                        | Результат                                              |
| -------------- | ----------------------------------------- | ------------------------------------------------------ |
| `sandbox_list` | `status?`, `limit?`                       | Песочницы аккаунта с необязательным фильтром состояния |
| `sandbox_get`  | `sandbox_id`                              | Одна песочница по UUID или имени                       |
| `metrics_get`  | `sandbox_id`                              | Текущие метрики CPU, памяти и диска                    |
| `ports_list`   | `sandbox_id`                              | Открытые порты и URL превью                            |
| `files_read`   | `sandbox_id`, абсолютный `path`           | Содержимое файла и кодировка                           |
| `files_list`   | `sandbox_id`, абсолютный `path`, `depth?` | Элементы директории                                    |

Текущие метрики, порты и операции с файлами обращаются к управляющему компоненту-владельцу песочницы. Они могут завершиться ошибкой, если песочница не запущена или ее управляющий компонент-владелец недоступен.

### Платформа и аккаунт[​](#platform-and-account "Прямая ссылка на Платформа и аккаунт")

| Инструмент          | Основные аргументы             | Результат                                                                                   |
| ------------------- | ------------------------------ | ------------------------------------------------------------------------------------------- |
| `automation_list`   | нет                            | Автоматизации аккаунта                                                                      |
| `automation_get`    | `id` автоматизации             | Одна автоматизация и метаданные последнего запуска                                          |
| `template_list`     | нет                            | Собственные и публичные шаблоны, видимые аккаунту                                           |
| `template_versions` | `name` шаблона                 | Версии и доступность по узлам                                                               |
| `skills_catalog`    | нет                            | Каталог внешних навыков ассистентов                                                         |
| `account_overview`  | нет                            | Учетная запись, квота, состояния песочниц, недавняя активность и число персональных токенов |
| `account_usage`     | `since_days?`                  | Потребление вычислений и хранилища за `1..366` дней; по умолчанию `30`                      |
| `storage_list`      | `prefix?`, `cursor?`, `limit?` | Страница метаданных объектов и курсор продолжения                                           |
| `storage_get`       | `key` объекта                  | Метаданные одного объекта                                                                   |

`storage_get` не возвращает байты объекта. Для передачи содержимого используйте скачивание через REST или операции с presigned URL.

### Hosted MCP[​](#hosted-mcp "Прямая ссылка на Hosted MCP")

| Инструмент           | Основные аргументы      | Результат                                                  |
| -------------------- | ----------------------- | ---------------------------------------------------------- |
| `hosted_mcp_list`    | нет                     | Инстансы Hosted MCP в аккаунте                             |
| `hosted_mcp_get`     | `id` инстанса           | Определение, состояние жизненного цикла, URL и потребление |
| `hosted_mcp_catalog` | нет                     | Курируемые определения Hosted MCP                          |
| `hosted_mcp_logs`    | `id` инстанса, `lines?` | До `1..1000` строк журнала; по умолчанию `200`             |

Чтение логов не пробуждает инстанс после засыпания при простое. Если запущенный инстанс не может предоставить логи, результат содержит `available: false`.

## Инструменты записи[​](#write-tools "Прямая ссылка на Инструменты записи")

Инструменты записи требуют персональный токен или OAuth-подключение с правами `full`. Успешные вызовы записи попадают в поток аудита аккаунта.

### Жизненный цикл песочницы и часть платформы для работы с ее данными[​](#sandbox-lifecycle-and-data-plane "Прямая ссылка на Жизненный цикл песочницы и часть платформы для работы с ее данными")

| Инструмент          | Основные аргументы                                                                                                      | Действие                                                                               |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `sandbox_create`    | `template` и необязательные ресурсы, переменные окружения, секреты, репозиторий, хранилище и настройки жизненного цикла | Создает песочницу через те же механизмы квот, размещения и идемпотентности, что и REST |
| `sandbox_resume`    | `sandbox_id`, `vcpu?`, `ram_mb?`                                                                                        | Возобновляет остановленную песочницу                                                   |
| `sandbox_stop`      | `sandbox_id`                                                                                                            | Останавливает, сохраняя состояние файловой системы                                     |
| `sandbox_hibernate` | `sandbox_id`                                                                                                            | Гибернирует и сохраняет снимок памяти                                                  |
| `sandbox_wake`      | `sandbox_id`                                                                                                            | Пробуждает песочницу в гибернации                                                      |
| `sandbox_delete`    | `sandbox_id`                                                                                                            | Безвозвратно удаляет файловую систему песочницы                                        |
| `sandbox_exec`      | `sandbox_id`, `cmd`, необязательные `args`, `cwd`, `env`, `timeout_ms`, `user`                                          | Запускает одну команду с буферизацией вывода                                           |
| `files_write`       | `sandbox_id`, абсолютный `path`, `content`, `encoding?`, `overwrite?`                                                   | Записывает текст или байты в кодировке base64                                          |
| `ports_add`         | `sandbox_id`, `port`, необязательные поддомен, путь и поля аутентификации                                               | Открывает порт для превью                                                              |
| `ports_remove`      | `sandbox_id`, `port`                                                                                                    | Закрывает открытый порт                                                                |

`sandbox_create` по умолчанию асинхронен. Он возвращает результат после запуска VM, пока клонирование репозитория или другая подготовка может продолжаться. Опрашивайте `sandbox_get`, пока `provisioning.status` не станет `ready`, либо передайте `wait_until_ready: true`. При повторе `sandbox_create`, который не должен создать вторую песочницу, задайте `idempotency_key`.

`sandbox_exec` буферизует вывод и ограничивает `stdout` и `stderr` значением 64 КиБ для каждого потока. Проверяйте флаг `truncated`. Это не терминал со стримингом.

### Жизненный цикл Hosted MCP[​](#hosted-mcp-lifecycle "Прямая ссылка на Жизненный цикл Hosted MCP")

| Инструмент            | Основные аргументы                                                   | Действие                                                                                              |
| --------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `hosted_mcp_create`   | `name` и `catalog_key` либо определение источника, заданное напрямую | Создает и по умолчанию начинает развертывание                                                         |
| `hosted_mcp_enable`   | `id` инстанса                                                        | Включает публичный порт или разворачивает отсутствующую песочницу, в которой работает сервер          |
| `hosted_mcp_disable`  | `id` инстанса                                                        | Убирает публичный доступ и останавливает песочницу, в которой работает сервер                         |
| `hosted_mcp_redeploy` | `id` инстанса                                                        | Заменяет песочницу, в которой работает сервер, не меняя идентификатор в адресе, токен и публичный URL |
| `hosted_mcp_test`     | `id` инстанса                                                        | Выполняет MCP `initialize` и `tools/list`; может пробудить инстанс                                    |
| `hosted_mcp_delete`   | `id` инстанса                                                        | Удаляет сущность и песочницу, в которой работает сервер                                               |

`hosted_mcp_create` возвращает bearer-токен инстанса в открытом виде только один раз. Сохраните его сразу. Развертывание асинхронно: опрашивайте `hosted_mcp_get`, пока `status` не станет `ready`.

## Форма вызова и результата[​](#tool-call-and-result-shape "Прямая ссылка на Форма вызова и результата")

Структура сообщения протокола соответствует стандартному MCP. Например, MCP-клиент вызывает:

```
{
  "name": "sandbox_list",
  "arguments": {
    "status": "running",
    "limit": 20
  }
}
```

Текущие инструменты возвращают один текстовый элемент содержимого, в поле `text` которого находится сериализованный JSON:

```
{
  "content": [
    {
      "type": "text",
      "text": "[{\"sandbox_id\":\"example\",\"state\":\"running\"}]"
    }
  ],
  "isError": false
}
```

Перед использованием полей разберите значение `text` как JSON. Не рассчитывайте на наличие `structuredContent`.

Сейчас сервер публикует 35 инструментов: 19 чтения и 16 записи. Всегда предпочитайте актуальный результат `tools/list` сохраненному списку, поскольку инструменты, зависящие от инсталляции, продолжают объявляться, даже когда функция, на которую они опираются, выключена.

## Границы доступности[​](#availability-boundaries "Прямая ссылка на Границы доступности")

Сам эндпоинт MCP управления платформой подключен на каждом шлюзе, но некоторые инструменты зависят от конфигурации инсталляции:

* вызовы `hosted_mcp_*` завершаются ошибкой, когда Hosted MCP выключен;
* вызовы `storage_*` завершаются ошибкой, когда объектное хранилище аккаунта недоступно;
* `skills_catalog` завершается ошибкой, когда каталог внешних навыков ассистентов выключен.

Видимость инструмента не означает, что функция, на которую он опирается, включена. Обрабатывайте ошибку инструмента и переходите к соответствующему REST-сценарию или пользовательскому сценарию только тогда, когда этот способ доступен.

## Ошибки и ограничения частоты запросов[​](#errors-and-rate-limits "Прямая ссылка на Ошибки и ограничения частоты запросов")

| Ошибка                                                                                         | Наблюдаемый результат                                                                |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Bearer-токен отсутствует или неверен                                                           | HTTP `401` до обработки JSON-RPC                                                     |
| Неверные аргументы, конфликт, необрабатываемые входные данные или слишком большое тело запроса | Ошибка MCP `invalid_params`                                                          |
| Нет песочницы, автоматизации, инстанса Hosted MCP или другого ресурса                          | Ошибка MCP `resource_not_found`                                                      |
| Токен `read_only` вызывает инструмент записи или у клиента нет прав                            | Ошибка MCP `invalid_request`                                                         |
| Превышено ограничение частоты запросов или недоступна функция инсталляции                      | Ошибка MCP `internal_error` с безопасным сообщением, из которого понятно, что делать |
| Внутренняя ошибка базы данных или исходного сервера                                            | Ошибка MCP `internal_error` с общим текстом `internal error`                         |

На весь трафик `/mcp` действует ограничение частоты запросов по IP. Перед изменяющей операцией инструменты записи также используют ограничение частоты запросов шлюза для каждого аккаунта.

Для учетных данных OAuth (`jroa_`) дополнительно действуют бюджеты допуска в Redis: 600 запросов за 60 секунд на подключение и 3000 на аккаунт. Ротация токена доступа сохраняет бюджет подключения. Превышение любого бюджета дает HTTP `429` до обработки JSON-RPC; недоступность Redis — HTTP `503` (`auth.temporarily_unavailable`). Персональные токены и JWT веб-интерфейса не расходуют эти OAuth-бюджеты. Проверка владельца MCP-сессии по-прежнему использует Redis для всех типов учетных данных.

## Связанные страницы[​](#related "Прямая ссылка на Связанные страницы")

* [Персональные токены](/accounts/personal-access-tokens.md)
* [Основы работы с API](/developers/api-fundamentals.md)
* [Справочник REST API](/api-reference/rest.md)
* [Входящие вебхуки](/api-reference/webhooks.md)
