Оформление

MCP: внешний AI-агент и контракт проекта

Где подключить: Настройки проекта → Интеграции → Добавить → MCP. MCP предоставляет внешнему клиенту инструменты Sales Ninja; это не Kohai внутри кабинета и не REST с X-SN-TOKEN.

Подготовьте доступ ​

  1. Сначала выберите области данных, которые разрешаете внешнему помощнику. Оставьте выключенными области, к которым ему не нужен доступ.
  2. Выбранные области ограничивают доступ к этому проекту. Проверьте состав каждой области в списке перед сохранением; название области само по себе не означает доступ только для чтения.
  3. После создания откройте вкладку «Подключение» и выберите свой клиент. Новые секреты показываются один раз: скопируйте их в этот клиент до закрытия окна.

Данные подключения ​

Откройте Настройки проекта → Интеграции → Добавить, выберите сервис и задайте понятное название подключения.

После сохранения ​

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

Если подключение не работает ​

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

Инструкции сервиса ​

Параметры и результат изменений ​

  • Сначала клиент получает список доступных инструментов. Набор зависит от прав и данных проекта; недоступный инструмент вызвать нельзя.
  • Параметры выражают бизнес-намерение типизированными полями. Агент не должен передавать поля, которых нет в описании инструмента, или придумывать идентификатор новой сущности.
  • save_* создаёт или полностью сохраняет объект, update_* меняет только явно переданные поля, delete_* удаляет; идентифицируемые дочерние сущности имеют отдельные create/update/delete tools.
  • После успешной записи ответ содержит актуальную entity с идентификаторами и значениями, сохранёнными сервером. Именно её продолжайте использовать, а не исходный черновик.
  • В запросах и ответах — camelCase; enum и допустимые варианты берите из tool schema/constructor, не переводите и не переименовывайте.

Как исправить ошибку ​

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

json
{
  "status": "error",
  "code": "ValidationFailed",
  "message": "...",
  "hint": "...",
  "jsonPath": "$.options[0]",
  "validEnumValues": ["working", "stopped", "archived"]
}

Стабильные code: WriteRequiresAuthenticatedUser, WriteRequiresEditorRole, ValidationFailed, InvalidArgument, InvalidJson, InvalidOperation, Canceled, InternalError. Чтобы исправить запрос, используйте hint, jsonPath и validEnumValues; менять casing или угадывать другое имя поля нельзя.

Минимальный рабочий маршрут агента ​

  1. Вызвать list/get tool и прочитать текущую entity либо получить constructor/catalog.
  2. Выбрать tool по намерению и заполнить только его typed fields.
  3. Для создания не передавать id; для обновления использовать серверный id прочитанной entity.
  4. После записи заменить локальный черновик на возвращённую entity.
  5. При ошибке выполнить hint или объяснить, что нужно исправить. Повторение того же запроса проблему не устраняет.

Безопасность и границы ​

Набор доступных инструментов зависит от прав, подключений и данных проекта. Инструкции по сущностям смотрите в Public REST manage для описания возможностей. Параметры MCP-запроса всегда берите из описания выбранного инструмента.

Связано: роли проекта, Kohai, каталог интеграций.