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 в веб-интерфейсе.

Workspace Header

Укажите целевой workspace в заголовке:

X-Workspace: my-workspace

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

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

{
  "mcpServers": {
    "onreza": {
      "url": "https://api.onreza.app/mcp",
      "headers": {
        "Authorization": "Bearer nrz_xxxxxxxxxxxxxxxx",
        "X-Workspace": "my-workspace"
      }
    }
  }
}

Endpoint

POST /mcp

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

Совет

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

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

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "deploy",
    "arguments": {
      "project": "my-app",
      "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	Название ветки	да
commit	string	Конкретный commit SHA	нет

Пример:

{
  "name": "deploy",
  "arguments": {
    "project": "my-app",
    "branch": "feature/new-api"
  }
}

get-deployment-status

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

Параметры:

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

get-build-logs

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

Параметры:

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

get-runtime-logs

Получает runtime логи приложения.

Параметры:

Параметр	Тип	Описание
projectId	string	UUID проекта
lines	number	Количество строк (по умолчанию 100)

rollback

Выполняет откат к предыдущему деплою.

Параметры:

Параметр	Тип	Описание
projectId	string	UUID проекта
target	string	ID целевого деплоя (опционально, по умолчанию предыдущий)

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.app/mcp",
      "headers": {
        "Authorization": "Bearer nrz_xxxxxxxxxxxxxxxx",
        "X-Workspace": "my-workspace"
      }
    }
  }
}

Совет

Сохраните 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 используется:

Роль	Доступные действия
OWNER	Все операции
ADMIN	Все операции, кроме удаления workspace
MEMBER	Чтение, деплой, управление env vars в разрешённых проектах
VIEWER	Только чтение

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

Осторожно

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

Rate Limits

Операция	Лимит
Все MCP запросы	1000/минуту
Deploy операции	60/минуту
Логи	300/минуту

При превышении лимита возвращается ошибка 429 Too Many Requests.

Ошибки

Стандартный формат ошибки

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32600,
    "message": "Invalid Request: Project not found"
  },
  "id": 1
}

Коды ошибок

Код	Описание
-32700	Parse error
-32600	Invalid Request
-32601	Method not found
-32602	Invalid params
-32603	Internal error
401	Unauthorized — неверный или отсутствующий API key
403	Forbidden — недостаточно прав
404	Not Found — проект или деплой не найден
409	Conflict — параллельный деплой
429	Rate limit exceeded