MCP-сервер

MCP-сервер — компонент Deckhouse Development Portal (DDP, портала), который реализует протокол MCP (Model Context Protocol) и обеспечивает взаимодействие внешних AI-клиентов (таких как LM Studio, Claude Desktop и других) с порталом. Сервер работает по JSON-RPC 2.0 и предоставляет набор инструментов для работы с ресурсами портала и проксирования запросов во внешние инфраструктурные сервисы.

MCP — это открытый протокол для взаимодействия AI-моделей с внешними системами. Подробнее о протоколе можно узнать на официальном сайте MCP.

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

Инструменты портала включают операции API и специализированные инструменты с префиксом curated_. Любой инструмент требует включения в доступную пользователю MCP-коллекцию. Инструменты типа external доступны после синхронизации каталога MCP-сервера и добавления инструментов в MCP-коллекцию. Инструменты типа custom создаются вручную в подразделе «MCP-инструменты» и доступны после добавления в MCP-коллекцию.

Названия инструментов

В MCP-клиенте используйте название из tools/list. Платформенный агент и OpenCode рабочего пространства показывают модели те же инструменты с дополнительным префиксом ddp_. При настройке коллекции выбирайте название без этого префикса:

Ниже приведены названия для MCP-клиента и каталога коллекций. В инструкциях платформенному агенту добавляйте ddp_; внешний агент может задавать собственное представление названий для модели.

Инструменты операций API

В «AI» → «MCP» → «Каталог» отображаются названия инструментов, например get_resources и get_resource_entities, их описания и соответствующие HTTP-методы и пути API. По нажатию на название инструмента открывается схема его аргументов. Инструменты объединены в группы, например «Каталог», «Обозреватель каталога», «Действия», «Процессы и автоматизации» и «Рабочие пространства». Специализированные инструменты находятся в группе «Курируемые».

Аргументы инструмента описаны в inputSchema ответа tools/list. Например, run_process — операция API, а curated_run_process — специализированный инструмент с параметрами, описанными ниже. Их аргументы различаются.

Результат инструмента операции содержит HTTP-статус, тип содержимого, способ кодирования и тело ответа. Например:

{
  "status": 200,
  "contentType": "application/json; charset=utf-8",
  "encoding": "json",
  "body": []
}

Для JSON тело передаётся как JSON. Для остальных форматов используется encoding: "base64". Неуспешный вызов возвращает MCP-результат с isError: true; ошибки «Обозревателя каталога» также поясняют, как исправить запрос.

Инструменты работы с каталогом

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

Результаты и счётчики ограничены доступными пользователю данными. Если видна хотя бы одна сущность, инструменты также показывают схему её ресурса для запросов по свойствам. Обход связей не проходит через недоступные сущности.

В каталоге коллекций и внешнем MCP-клиенте используются следующие названия. Для модели платформенного агента и OpenCode к ним добавляется ddp_, например ddp_query_catalog:

Описание и точные аргументы доступны в «AI» → «MCP» → «Каталог» и в inputSchema ответа tools/list.

Следующие примеры показывают объект params для tools/call. При передаче тела запроса API используйте аргумент body. Сначала вызовите get_catalog_schema, чтобы узнать существующие идентификаторы ресурсов, свойств и связей. Идентификаторы services и language в примере замените на значения своей установки.

Сущности моих команд

Запрос группирует сервисы команд текущего пользователя по языку разработки:

{
  "name": "query_catalog",
  "arguments": {
    "body": {
      "resource": "services",
      "where": {"field": "team", "op": "in", "value": {"context": "myTeams"}},
      "groupBy": "properties.language"
    }
  }
}

{"context":"myTeams"} подставляет команды вызывающего пользователя. Для фильтра по владельцу используется {"context":"me"}. countOnly: true возвращает количество сущностей без списка; groupBy возвращает группы с их счётчиками. В сгруппированном ответе total — число групп, entities — число найденных сущностей.

Для выборки нескольких условий объедините их в where.and или where.or. Доступны сравнения eq, ne, gt, gte, lt, lte, in, contains, containsAny, isEmpty, isNotEmpty и between; набор зависит от типа поля. Обращение к properties.<идентификатор> требует параметра resource.

Неуспешные запуски за вчера

Запрос выбирает запуски со статусом Failed за предыдущий календарный день в часовом поясе Москвы:

{
  "name": "list_process_runs",
  "arguments": {
    "body": {
      "status": ["Failed"],
      "team": {"context": "myTeams"},
      "since": {"calendar": "day", "offset": -1},
      "timezone": "Europe/Moscow",
      "limit": 20
    }
  }
}

Для скользящего периода используйте since: {"last":"24h"}. countOnly: true возвращает количество запусков; groupBy группирует их по status, process, initiator, entity или day. Эти два режима не совмещаются. Для диагностики передайте UUID найденного запуска в get_process_run как run_uuid.

В чате портал передаёт часовой пояс браузера. Внешний MCP-клиент задаёт timezone явно; без него используется UTC. Неизвестный часовой пояс отклоняет запрос.

Проверка перед запуском процесса

Перед выполнением используйте последовательность:

1. Найдите сущность через search_catalog и получите доступные операции через find_operations.
2. Передайте UUID ресурса, сущности и процесса в check_process_readiness. В body укажите значения запуска: selectedProperties, actions, context, skippedElementUuids и agentProviderRefs, когда они нужны.
3. Проверьте ready, blockers и approvalRequired. Проверка возвращает первое препятствие; исправьте его по подсказке и повторите вызов. Значения по умолчанию здесь не подставляются.
4. Для выполнения отдельно вызовите операцию API run_process либо специализированный curated_run_process с его собственной схемой аргументов.

Проверка требует control:processes глобально, на ресурс или сущность. Читаемая операция не обязательно доступна для запуска. Между проверкой и запуском состояние может измениться, поэтому итоговый результат проверяется по ответу запуска.

Ограничения и неполные ответы

При работе со списками учитывайте размер ответа и ограничения запроса:

• limit по умолчанию равен 20, максимум — 500. Если hasMore: true, продолжайте с offset, увеличенным на returned. При ограничении размера ответа строк может быть меньше, чем запрошено.
• Для графа связей depth задаётся от 1 до 5. При truncated: true следуйте hints: уточните тип связи, глубину или лимит. Граф не поддерживает offset.
• Дерево where допускает до четырёх уровней вложенности и 20 условий. Если запрос слишком сложен, сузьте выборку или глубину обхода связей.
• Карточка get_entity_summary сокращает длинные описания и значения. Для полного поля используйте query_catalog с fields и фильтром по UUID.
• Диагностика запуска отмечает недостающие факты в unknown. Отсутствующее время следующего повтора или событие шага нельзя считать подтверждением ошибки.

При отказе инструмент возвращает isError: true с причиной и подсказкой. Исправьте указанный аргумент, уточните неоднозначную ссылку или уменьшите запрос.

curated_get_external_data

Выполнить HTTP-запрос к внешнему сервису с учётными данными пользователя.

Параметры:

Учётные данные и заголовки берутся из настроек внешнего сервиса в портале.

Возвращает: результат HTTP-запроса к внешнему сервису.

Пример:

Получи список проектов из внешнего сервиса GitLab

curated_get_processes

Получить список процессов с параметрами запуска.

Параметры:

Возвращает: для каждого процесса — UUID, идентификатор, название, описание, ресурсы, параметры запуска (properties) и пути контекста запуска, которые читает процесс (contextPaths). С include_step_properties — также задачи процесса с параметрами действий (steps). Поле contextPathsComplete показывает, учтены ли тела действий при сборе путей; перед подготовкой запуска запросите include_step_properties: true. Схема элементов процесса не возвращается.

Пример:

Получи список процессов

curated_get_service_templates

Получить шаблоны микросервисов из реестра шаблонов.

Параметры:

Возвращает: для каждого шаблона — templateId, version, source, название, описание, язык, признак текущей версии и параметры шаблона (values). Значения templateId, version и source передаются в контекст запуска процесса создания микросервиса как context.template.

Пример:

Получи список заготовок сервисов

curated_run_process

Запустить процесс для сущности.

Параметры:

Возвращает: сообщение о запуске и UUID созданного запуска процесса (instanceUUID).

Для сущности одновременно может выполняться только один запуск одного процесса: повторный запуск возвращает ошибку 409. Для запуска требуется разрешение control:processes на уровне портала, ресурса или сущности.

Пример:

Запусти процесс «Deploy» для сущности «api-gateway» с версией 1.4.0

curated_get_process_instance

Получить один запуск процесса с хранилищем.

Параметры:

Возвращает: статус запуска, время, активные элементы и хранилище процесса. Для статусов Failed, Timeout и Partially Completed ответ содержит поле failureReason: элемент, на котором произошла ошибка, итоговое сообщение и последние строки лога этого элемента.

Пример:

Покажи результат экземпляра процесса 3fa85f64-5717-4562-b3fc-2c963f66afa6

Навыки

Инструменты чтения навыков передают инструкции и дополнительные файлы:

В обычном MCP-клиенте версия выбирается меткой; без неё используется последняя активная. В запуске агента доступ ограничен назначенными ему навыками и зафиксированными версиями. Бинарные файлы и файлы больше 1 МиБ через curated_get_skill_file не читаются.

Рабочие пространства

Инструменты позволяют подготовить рабочее пространство из чата:

provider можно не передавать, когда подходящий провайдер уже задан в контексте чата. При вызове вне такого контекста укажите его явно. parameters — объект значений переменных шаблона; ttl_hours — целое число от 1 до 720.

curated_attach_workspace работает только в контексте агента, отвечающего в чате портала. Используйте последовательность: получить шаблоны, создать пространство, дождаться готовности, прикрепить его к чату.

Подключение MCP-сервера

LM Studio

LM Studio 0.3.17 и новее поддерживает удалённые MCP-серверы. Серверы добавляются в файле mcp.json.

Чтобы подключить LM Studio к MCP-серверу портала:

1. В портале откройте «Профиль» и создайте API-токен.

2. В LM Studio откройте вкладку «Program» на правой боковой панели и выберите «Install» → «Edit mcp.json».

3. Добавьте MCP-сервер портала в объект mcpServers:

   {
     "mcpServers": {
       "ddp": {
         "url": "https://<DOMAIN>/api/v2/mcp",
         "headers": {
           "Authorization": "Bearer <API_TOKEN>"
         }
       }
     }
   }

   Где:

   • <DOMAIN> — домен портала;
   • <API_TOKEN> — API-токен портала.

4. Сохраните файл.

После подключения модель может вызывать встроенные инструменты из раздела «Доступные инструменты» и инструменты из доступных вам MCP-коллекций. Все вызовы выполняются с вашими правами доступа.

Подключение в других MCP-клиентах

MCP-сервер принимает запросы JSON-RPC 2.0 по HTTP. Для подключения клиента используйте следующие параметры:

• URL эндпоинта: https://<DOMAIN>/api/v2/mcp, где <DOMAIN> — домен портала.
• HTTP-метод: POST.
• Аутентификация: заголовок Authorization: Bearer <API_TOKEN>, где <API_TOKEN> — ваш API-токен портала из раздела «Профиль».

Сервер поддерживает следующие методы JSON-RPC:

• initialize — возвращает информацию о сервере и версию протокола 2024-11-05;
• tools/list — возвращает список инструментов, доступных пользователю;
• tools/call — вызывает инструмент.

Другие методы возвращают ошибку -32601 (Method not found).

Пример запроса к MCP-серверу

HTTP-заголовки:

Authorization: Bearer <API_TOKEN>
Content-Type: application/json

Тело запроса:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_resource_entities",
    "arguments": {
      "resource_uuid": "<RESOURCE_UUID>"
    }
  }
}

Пример ответа от MCP-сервера

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"status\":200,\"contentType\":\"application/json; charset=utf-8\",\"encoding\":\"json\",\"body\":{\"response\":[],\"error\":null}}"
      }
    ]
  }
}

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

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

• Все запросы к MCP-серверу должны проходить аутентификацию с помощью API-токена из раздела «Профиль». Токен передаётся в заголовке Authorization: Bearer <API_TOKEN>.
• Права доступа соответствуют правам вашего пользователя в портале.

Права доступа:

• Инструменты работают с теми же правами, что и пользователь.
• curated_run_process, curated_create_workspace, curated_attach_workspace и изменяющие операции API выполняют действия от имени пользователя. curated_get_external_data также может отправить POST, PUT, PATCH или DELETE во внешний сервис.
• Если у вас нет доступа к ресурсу, инструмент вернёт ошибку доступа.
• Данные фильтруются в соответствии с вашими правами RBAC.

Устранение неполадок

Не удаётся подключиться к серверу

Если не получается подключиться к серверу:

• Проверьте правильность URL (должен заканчиваться на /api/v2/mcp).
• Убедитесь, что API-токен действителен.
• Проверьте, что портал доступен с вашего компьютера.
• Проверьте настройки файрвола и прокси.

Ошибка аутентификации

Если не проходит аутентификация:

• Проверьте правильность формата токена.
• Убедитесь, что токен не истёк.
• Убедитесь, что используется заголовок Authorization: Bearer <API_TOKEN>.

Инструмент возвращает ошибку доступа

Если при обращении к инструменту возвращается ошибка доступа:

• Убедитесь, что у вашего пользователя есть права на доступ к запрашиваемому ресурсу.
• Проверьте правильность названия или идентификатора ресурса.
• Обратитесь к администратору портала для проверки прав доступа.

Данные не возвращаются

Если данные не возвращаются:

• Проверьте правильность параметров запроса.
• Убедитесь, что ресурс существует и содержит сущности.
• Проверьте логи портала для получения подробной информации об ошибке.