Перейти к основному содержимому
Открыть Markdown

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

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

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

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

Аутентификация​

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

Authorization: Bearer your-personal-access-token

Для постоянной конфигурации клиента используйте персональный токен:

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

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

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

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.

Подключение​

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

ПараметрЗначение
Способ передачиStreamable HTTP
URLhttps://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_only и full и OAuth-подключений с правами full.

Песочницы и часть платформы для работы с их данными​

ИнструментОсновные аргументыРезультат
sandbox_liststatus?, limit?Песочницы аккаунта с необязательным фильтром состояния
sandbox_getsandbox_idОдна песочница по UUID или имени
metrics_getsandbox_idТекущие метрики CPU, памяти и диска
ports_listsandbox_idОткрытые порты и URL превью
files_readsandbox_id, абсолютный pathСодержимое файла и кодировка
files_listsandbox_id, абсолютный path, depth?Элементы директории

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

Платформа и аккаунт​

ИнструментОсновные аргументыРезультат
automation_listнетАвтоматизации аккаунта
automation_getid автоматизацииОдна автоматизация и метаданные последнего запуска
template_listнетСобственные и публичные шаблоны, видимые аккаунту
template_versionsname шаблонаВерсии и доступность по узлам
skills_catalogнетКаталог внешних навыков ассистентов
account_overviewнетУчетная запись, квота, состояния песочниц, недавняя активность и число персональных токенов
account_usagesince_days?Потребление вычислений и хранилища за 1..366 дней; по умолчанию 30
storage_listprefix?, cursor?, limit?Страница метаданных объектов и курсор продолжения
storage_getkey объектаМетаданные одного объекта

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

Hosted MCP​

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

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

Инструменты записи​

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

Жизненный цикл песочницы и часть платформы для работы с ее данными​

ИнструментОсновные аргументыДействие
sandbox_createtemplate и необязательные ресурсы, переменные окружения, секреты, репозиторий, хранилище и настройки жизненного циклаСоздает песочницу через те же механизмы квот, размещения и идемпотентности, что и REST
sandbox_resumesandbox_id, vcpu?, ram_mb?Возобновляет остановленную песочницу
sandbox_stopsandbox_idОстанавливает, сохраняя состояние файловой системы
sandbox_hibernatesandbox_idГибернирует и сохраняет снимок памяти
sandbox_wakesandbox_idПробуждает песочницу в гибернации
sandbox_deletesandbox_idБезвозвратно удаляет файловую систему песочницы
sandbox_execsandbox_id, cmd, необязательные args, cwd, env, timeout_ms, userЗапускает одну команду с буферизацией вывода
files_writesandbox_id, абсолютный path, content, encoding?, overwrite?Записывает текст или байты в кодировке base64
ports_addsandbox_id, port, необязательные поддомен, путь и поля аутентификацииОткрывает порт для превью
ports_removesandbox_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_createname и catalog_key либо определение источника, заданное напрямуюСоздает и по умолчанию начинает развертывание
hosted_mcp_enableid инстансаВключает публичный порт или разворачивает отсутствующую песочницу, в которой работает сервер
hosted_mcp_disableid инстансаУбирает публичный доступ и останавливает песочницу, в которой работает сервер
hosted_mcp_redeployid инстансаЗаменяет песочницу, в которой работает сервер, не меняя идентификатор в адресе, токен и публичный URL
hosted_mcp_testid инстансаВыполняет MCP initialize и tools/list; может пробудить инстанс
hosted_mcp_deleteid инстансаУдаляет сущность и песочницу, в которой работает сервер

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

Форма вызова и результата​

Структура сообщения протокола соответствует стандартному 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 сохраненному списку, поскольку инструменты, зависящие от инсталляции, продолжают объявляться, даже когда функция, на которую они опираются, выключена.

Границы доступности​

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

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

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

Ошибки и ограничения частоты запросов​

ОшибкаНаблюдаемый результат
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 для всех типов учетных данных.