Инструменты

Инструмент — роут пользовательской карты API-платформы с типом mcp и секцией mcp. Отдельный код в MCP-шлюзе не нужен: при каждом запросе шлюз читает итоговые карты роутов.

Как добавить инструмент

1. Опишите роут в пользовательской карте роутов: адрес, HTTP-метод, параметры и контроллер.
2. Укажите тип RouteConfig::ROUTE_TYPE_MCP. У роута другого типа или без типа секция mcp игнорируется.
3. Задайте авторизацию SecurityConfig::AUTH => SecurityConfig::TOKEN. Тип токена не указывайте: по умолчанию используется access-токен.
4. Укажите группы в whitelist роута: «MCP: Клиенты» (NATIVE_MCP_CLIENT), если инструмент нужен всем агентам, или отдельную группу для части пользователей, см. «Доступ и группы».
5. Добавьте секцию mcp с кодом и описанием инструмента.
6. Очистите кеш API-платформы.

Примеры роутов и контроллеров — в разделе «Примеры инструментов»: «Собственный инструмент», «Название сайта», «Версия модуля» и «Список заказов».

Чтобы встроенный инструмент отдавал данные проекта, объявите в пользовательской карте роут с тем же методом и адресом, например GET mcp/orders, и укажите свой контроллер. Такой роут заменяет встроенный целиком, поэтому перенесите в него все настройки, включая параметры, группы и секцию mcp.

Роут без whitelist агент видит при входе в группу «MCP: Клиенты», но обычным REST-запросом его может вызвать любой пользователь с access-токеном. Поэтому группы указывают всегда.

Контроллер

Аргументы агента метод получает через Context::getCurrent()->getParams(): шлюз уже проверил их по схеме.

Шлюз не фильтрует результат и не требует для него схемы: состав ответа задаёт контроллер, а права на данные проверяет он же.

Секция mcp

Ключи секции — константы Mcp\ToolConfig API-платформы. Используйте их вместо строк: тот же контракт читает MCP-шлюз.

Код инструмента: от 1 до 128 символов, латинские буквы, цифры, _, . и -. Коды должны быть уникальными среди всех опубликованных роутов: дубликат или недопустимый код делает недоступным весь каталог.

Описание роута RouteConfig::DESCRIPTION предназначено для людей и выводится в документации OpenAPI. Описание инструмента ToolConfig::DESCRIPTION читает модель: по нему агент решает, когда вызывать инструмент. Укажите в нём, что возвращает инструмент и в каких случаях его использовать.

Подсказки задаются булевыми значениями:

Клиент может использовать подсказки, например, чтобы запросить подтверждение. Они не заменяют проверок в контроллере.

Какие роуты публикуются

Инструментом становится роут, у которого выполнены все условия:

• тип RouteConfig::ROUTE_TYPE_MCP;
• непустая секция mcp с кодом ToolConfig::CODE;
• роут активен;
• авторизация SecurityConfig::AUTH => SecurityConfig::TOKEN по access-токену.

Сверх этих условий шлюз никогда не публикует сам роут /mcp и роуты выдачи токенов.

Если у роута с секцией mcp другая авторизация, инструмент в каталог не попадёт, а на вызов по коду шлюз ответит ошибкой с указанием требуемой авторизации, а не «инструмент не найден».

Отдельного флага активности у секции mcp нет. При RouteConfig::ACTIVE => false роут отвечает 403 и пропадает из каталога. Чтобы снять инструмент с публикации, оставив REST-роут рабочим, уберите секцию.

Каталог учитывает пользовательское переопределение карт и текущие группы пользователя.

Аргументы инструмента

Схему аргументов шлюз строит из параметров роута:

• параметры адреса, например {status}, обязательны;
• типы string, integer и array переносятся в схему, вложенные параметры — во вложенные объекты и массивы;
• обязательная строка не принимает пустое значение, обязательная коллекция — пустой массив или объект;
• допустимые значения и диапазоны переносятся в ограничения схемы.

Перед выполнением аргументы проверяются по схеме. Затем роут выполняется общим конвейером API-платформы с исходным HTTP-методом: проверки доступа, лимиты, события и кеш результата сохраняются.

Встроенные инструменты

Все три инструмента только читают данные. Обе группы создаёт установщик шлюза, каждый инструмент разобран в разделе «Примеры инструментов».