OpenAPI и MCP: расширяем набор инструментов, не переписывая ядро

Когда агенту нужно обратиться к уже существующему сервису, первая реакция разработчика — написать адаптер внутри основного приложения. Для одного метода это кажется быстрым. Через несколько интеграций ядро обрастает клиентами, схемами авторизации и несовместимыми циклами обновления. OpenAPI и MCP позволяют провести границу иначе: внешний источник описывает инструменты контрактом, а шлюз подключает их без переноса бизнес-логики внутрь.

Это не магия «интеграции без разработки». Контракт нужно сократить до безопасной поверхности, секреты — вынести в хранилище секретов, полномочия — ограничить, ошибки — проверить. Зато команда может обновлять спецификацию или MCP-сервер отдельно от релиза ядра и яснее видеть, где заканчивается ответственность платформы.

OpenAPI: операция становится инструментом

Спецификация OpenAPI 3.x описывает эндпоинт, параметры, тело, ответ и схему авторизации. AiHummer может синтезировать вызываемый инструмент для каждой выбранной операции. В манифесте указываются адрес спецификации, префикс имён, разрешённые хосты и связь securityScheme с конфигурацией. Хорошие operationId и описания особенно важны: агенту нужна однозначная цель, а оператору — понятный журнал.

Не публикуйте весь корпоративный API только потому, что генератор умеет его прочитать. Создайте узкую спецификацию для нужного сценария: например, получить статус заявки и добавить внутренний комментарий, но не удалить клиента или поменять реквизиты. Чем меньше поверхность, тем проще права, тестирование и одобрение.

Allowed hosts ограничивает адреса, к которым может привести спецификация. Это часть защиты от неожиданных сетевых переходов, но не замена сетевой политике. Проверьте редиректы, DNS, TLS и доступность хоста из среды инстанса. Ошибка соединения должна возвращаться как понятный сбой инструмента, а не маскироваться выдуманным ответом.

MCP: отдельный сервер с собственным циклом

MCP полезен, когда поставщик уже публикует сервер инструментов или интеграция имеет сложную логику. Манифест фиксирует вид источника, транспорт, команду и параметры запуска. Сервер обновляется отдельно, но его версия, пакет и зависимости всё равно должны быть закреплены. Оператор проверяет происхождение, подпись, здоровье процесса и заявленные возможности.

У отдельного процесса появляются свои эксплуатационные вопросы: кто перезапускает сервер, где его журнал, как ограничена сеть, сколько времени занимает вызов, что происходит при зависании. Если MCP-инструмент меняет внешние данные, ему нужны те же минимальные полномочия, идемпотентность и одобрение, что и обычному встроенному инструменту.

Секреты и права

Токен не должен находиться в открытом manifest.json, URL спецификации или подсказке модели. Поле конфигурации объявляется секретным, а значение хранится в хранилище секретов. Внешняя учётная запись получает минимальную область доступа: инструмент чтения не нуждается в праве администрирования. Для персональных подключений отдельно решите, чьи данные доступны в конкретном диалоге.

Моделируемый сценарий записи начинайте только после стабильного чтения. Проверьте 401 при неверном ключе, 403 при недостаточной области доступа, 404 для отсутствующего объекта, 409 для конфликта, 429 при лимите и таймаут. Агент должен корректно сообщить, что действие не подтверждено, а оператор — увидеть идентификатор корреляции без раскрытия секрета.

Контракт не знает бизнес-правил

OpenAPI может сказать, что поле amount — число, но не знает лимит отдела, необходимость двух подписей или запрет изменения закрытого периода. MCP может предложить универсальную функцию, но не понимает внутреннюю матрицу ответственности. Сложные инварианты лучше проверять внутри узкого сервисного слоя, который откажет независимо от поведения модели.

Моделируемый пилот: агент читает статус заявки по номеру, затем готовит черновик комментария. Чтение доступно автоматически, публикация комментария ждёт подтверждения. Учётная запись видит только тестовый проект. Это пример, а не готовая конфигурация; конечные области доступа, каналы и эскалации определяет организация.

Порядок безопасного подключения

1. Выберите один измеримый пользовательский результат.
2. Оставьте в спецификации только нужные операции.
3. Проверьте манифест командой aihummer plugin validate.
4. Разместите секрет в хранилище секретов и выдайте минимальную область доступа.
5. Ограничьте хосты и сетевой маршрут.
6. Пройдите успешный вызов и основные классы ошибок.
7. Поместите рискованную запись под одобрение.
8. После изменения схемы повторите контрактные тесты.

Имена инструментов — часть интерфейса

Агент выбирает операцию по имени и описанию, поэтому расплывчатый operationId вроде run или update создаёт риск неверного вызова. Назовите действие предметно, укажите обязательные условия и опишите, что оно не делает. Ответ тоже должен иметь предсказуемую схему: явный статус, идентификатор объекта и ошибка, которую можно показать без секрета.

Версионируйте контракт до несовместимого изменения. Добавление необязательного поля обычно безопаснее, чем переименование или смена типа. Если поставщик изменяет спецификацию по плавающему URL, сохраните проверенную копию или хеш и настройте сигнал об изменении. Иначе новый набор инструментов может появиться между двумя запусками без ревью.

Ограничьте нагрузку на внешний сервис. Таймаут, число повторов и rate limit должны соответствовать его правилам. Автоматический повтор операции записи опасен без идемпотентного ключа и сверки результата. Для 429 лучше вернуть понятный статус и запланировать продолжение, чем немедленно создавать шторм одинаковых запросов.

Наблюдаемость соединяет стороны: идентификатор хода, имя инструмента, длительность, класс ответа и идентификатор корреляции провайдера. Логи не должны содержать токен или полное чувствительное тело. С такими полями команда видит, где именно возник сбой — в выборе инструмента, сети, авторизации, схеме или бизнес-валидации.

Когда выбрать не интеграции без кода

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

Выбор OpenAPI или MCP тоже не идеологический. Берите уже поддерживаемый поставщиком контракт, если он соответствует безопасности и эксплуатации. Для простого HTTP API спецификация обычно прозрачнее; для готового набора инструментов MCP сокращает адаптацию. В обоих случаях решение подтверждается пилотом, а не названием технологии.

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

Форматы источников описаны в интеграциях без кода, манифесты и CLI — в Plugin SDK, а хранение учётных данных — в документации по хранилищу секретов. Для первого знакомства подключите одну операцию только для чтения и сравните получившийся инструмент со своим контрактом безопасности.

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

На ревью покажите также операцию, которую сознательно не импортировали. Объяснение исключения — слишком широкие права, необратимый эффект или неясная схема — подтверждает, что поверхность выбирали по задаче, а не переносили целиком. Решение пересматривают при изменении контракта.