MCP Integration

MCP (Model Context Protocol) — протокол для интеграции AI агентов с ONREZA платформой. Endpoint предоставляет инструменты для автоматизации деплоев, управления проектами и мониторинга через stateless HTTP интерфейс.

Введение

Model Context Protocol (MCP) — открытый протокол, разработанный Anthropic, для стандартизации взаимодействия между AI ассистентами и внешними инструментами. ONREZA реализует MCP endpoint, позволяя AI агентам:

• Управлять проектами и деплоями
• Получать статус сборок и логи
• Настраивать переменные окружения
• Выполнять откаты к предыдущим версиям

Заметка

MCP endpoint работает в stateless режиме — каждый запрос независим и содержит всю необходимую информацию для обработки.

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

Все запросы к MCP endpoint требуют аутентификации через API key.

API Key

Передайте API key в заголовке Authorization:

Authorization: Bearer nrz_xxxxxxxxxxxxxxxx

API key можно создать в разделе Settings → API Keys в веб-интерфейсе.

Заметка

API key привязан к конкретному workspace при создании — целевой workspace определяется автоматически по ключу. Отдельный заголовок для выбора workspace указывать не нужно.

Пример конфигурации

Для использования MCP endpoint настройте конфигурацию в .mcp.json:

{
  "mcpServers": {
    "onreza": {
      "url": "https://api.onreza.ru/mcp",
      "headers": {
        "Authorization": "Bearer nrz_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Endpoint

POST /mcp

Streamable HTTP endpoint для вызова MCP инструментов.

Совет

Endpoint поддерживает streamable HTTP — можно получать результаты инструментов в реальном времени.

Формат запроса

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "deploy",
    "arguments": {
      "projectId": "0192a1b2-c3d4-7890-abcd-ef0123456789",
      "branch": "main"
    }
  },
  "id": 1
}

Формат ответа

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Deployment started successfully"
      }
    ]
  },
  "id": 1
}

Доступные инструменты

Инструмент	Описание
whoami	Информация о текущем пользователе
list-projects	Список проектов в workspace
get-project	Детали конкретного проекта
deploy	Создание деплоя из Git ветки
get-deployment-status	Статус деплоя
get-build-logs	Логи сборки деплоя
get-runtime-logs	Runtime логи приложения
rollback	Откат к предыдущему деплою
get-env-vars	Получение переменных окружения
set-env-var	Установка переменной окружения
delete-env-var	Удаление переменной окружения

whoami

Возвращает информацию о текущем пользователе.

Параметры: нет

list-projects

Возвращает список проектов в workspace.

Параметры: нет

get-project

Возвращает детали конкретного проекта.

Параметры:

Параметр	Тип	Описание
projectId	string	UUID проекта

deploy

Создаёт деплой из Git-репозитория проекта.

Параметры:

Параметр	Тип	Описание	Обязательный
projectId	string	UUID проекта	да
branch	string	Git-ветка. По умолчанию — основная ветка проекта	нет
commitSha	string	Конкретный commit SHA. По умолчанию — последний коммит ветки	нет

Пример:

{
  "name": "deploy",
  "arguments": {
    "projectId": "0192a1b2-c3d4-7890-abcd-ef0123456789",
    "branch": "feature/new-api"
  }
}

Заметка

Деплой через deploy работает только для проектов, подключённых к Git. Для проектов без Git-репозитория используйте CLI-команду nrz deploy.

get-deployment-status

Получает статус деплоя.

Параметры:

Параметр	Тип	Описание
deploymentId	string	UUID деплоя

get-build-logs

Получает логи сборки деплоя.

Параметры:

Параметр	Тип	Описание
deploymentId	string	UUID деплоя

get-runtime-logs

Получает runtime-логи приложения (HTTP-запросы: метод, путь, статус, длительность).

Параметры:

Параметр	Тип	Описание	Обязательный
projectId	string	UUID проекта	да
deploymentId	string	Фильтр по конкретному деплою	нет
limit	number	Количество строк лога	нет
search	string	Строка поиска по логам	нет
path	string	Фильтр по пути запроса	нет
method	string	Фильтр по HTTP-методу (GET, POST, …)	нет

rollback

Откатывает текущий LIVE-деплой на предыдущую версию — создаёт новый деплой из предыдущего артефакта.

Параметры:

Параметр	Тип	Описание
deploymentId	string	UUID текущего LIVE-деплоя, с которого выполняется откат

get-env-vars

Получает список переменных окружения проекта.

Параметры:

Параметр	Тип	Описание
projectId	string	UUID проекта

set-env-var

Устанавливает переменную окружения.

Параметры:

Параметр	Тип	Описание	Обязательный
projectId	string	UUID проекта	да
key	string	Имя переменной	да
value	string	Значение переменной	да
isSecret	boolean	Секретная переменная (true/false)	нет

delete-env-var

Удаляет переменную окружения.

Параметры:

Параметр	Тип	Описание
projectId	string	UUID проекта
key	string	Имя переменной

Примеры использования

Полный flow деплоя

1. Получение списка проектов

   Через UI: Dashboard → Projects

2. Создание деплоя

   Через UI:

   1. Перейдите в проект
   2. Нажмите Deploy
   3. Выберите ветку main

3. Проверка статуса деплоя

   Через UI: Project → Deployments

4. Получение логов сборки

   Через UI: Project → Deployments → выберите деплой → Logs

Управление переменными окружения

Установка переменной:

1. Project → Settings → Environment Variables
2. Нажмите Add Variable
3. Заполните поля:
   • Key: API_URL
   • Value: https://api.example.com
   • Environment: Production
4. Нажмите Save

Интеграция с Claude Code

Для использования MCP с Claude Code добавьте конфигурацию в .mcp.json или глобальные настройки:

{
  "mcpServers": {
    "onreza": {
      "url": "https://api.onreza.ru/mcp",
      "headers": {
        "Authorization": "Bearer nrz_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Совет

Сохраните API key в переменной окружения и используйте её в конфигурации:

{
  "headers": {
    "Authorization": "Bearer ${ONREZA_API_KEY}"
  }
}

Примеры запросов в Claude Code

После настройки MCP, Claude Code может выполнять команды напрямую:

User: Задеплой my-app из ветки feature/new-page
Claude: Создаю деплой проекта my-app из ветки feature/new-page...
        Деплой запущен: dep_xyz789
        URL: https://my-app-xyz789-workspace.onreza.app

User: Покажи логи последнего деплоя my-app
Claude: Получаю логи сборки...
        [12:34:56] Build started
        [12:34:57] Installing dependencies...
        [12:35:12] Build completed successfully

Безопасность

Scope инструментов

MCP инструменты работают в рамках прав владельца API key в его workspace. Каждый вызов проходит ту же проверку доступа, что и действия в веб-интерфейсе: например, deploy и set-env-var требуют права на запись, а list-projects и get-runtime-logs — права на чтение. Если у роли нет нужного права, инструмент вернёт ошибку доступа.

Подробнее о ролях и правах: Участники workspace.

Рекомендации

Осторожно

• Храните API key в безопасном месте (переменные окружения, секрет-менеджеры)
• Не коммитьте .mcp.json с реальными ключами в репозиторий
• Используйте ключи с минимально необходимыми правами
• Регулярно ротируйте API keys

Ограничения

Отдельных rate limits у MCP нет — действуют те же ограничения плана, что и для остального API. В частности deploy учитывает лимиты деплоев в день/час и доступный usage budget вашего плана. При их превышении инструмент вернёт ошибку с описанием причины. Подробнее: Лимиты и квоты.

Ошибки

MCP различает два типа ошибок.

Ошибки уровня протокола

Возвращаются как JSON-RPC error — например, при неудачной аутентификации:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "MCP endpoint requires API key authentication"
  },
  "id": null
}

Код	Описание
-32700	Parse error — некорректный JSON
-32600	Invalid Request — невалидный JSON-RPC запрос
-32601	Method not found
-32602	Invalid params — не прошла валидация аргументов инструмента
-32000	Ошибка аутентификации (HTTP 401)

Ошибки уровня инструмента

Бизнес-ошибки (проект не найден, недостаточно прав, превышен лимит) возвращаются как успешный ответ с флагом isError: true и текстом причины в content:

{
  "jsonrpc": "2.0",
  "result": {
    "content": [{ "type": "text", "text": "Project not found" }],
    "isError": true
  },
  "id": 1
}