Инструменты 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 |
| 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_only и full и
OAuth-подключений с правами full.
Песочницы и часть платформы для работы с их данными
| Инструмент | Основные аргументы | Результат |
|---|---|---|
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? | Элементы директории |
Текущие метрики, порты и операции с файлами обращаются к управляющему компоненту-владельцу песочницы. Они могут завершиться ошибкой, если песочница не запущена или ее управляющий компонент-владелец недоступен.
Платформа и аккаунт
| Инструмент | Основные аргументы | Результат |
|---|---|---|
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_list | нет | Инстансы Hosted MCP в аккаунте |
hosted_mcp_get | id инстанса | Определение, состояние жизненного цикла, URL и потребление |
hosted_mcp_catalog | нет | Курируемые определения Hosted MCP |
hosted_mcp_logs | id инстанса, lines? | До 1..1000 строк журнала; по умолчанию 200 |
Чтение логов не пробуждает инстанс после засыпания при простое. Если
запущенный инстанс не может предоставить логи, результат содержит
available: false.
Инструменты записи
Инструменты записи требуют персональный токен или OAuth-подключение с правами
full. Успешные вызовы записи попадают в поток аудита аккаунта.
Жизненный цикл песочницы и часть платформы для работы с ее данными
| Инструмент | Основные аргументы | Действие |
|---|---|---|
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_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.
Форма вызова и результата
Структура сообщения протокола соответствует стандартному 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 для всех типов учетных данных.