Оформление

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

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

Создать доступ ​

  1. Задайте имя и сохраните интеграцию.
  2. Сразу скопируйте OAuth Client ID/Secret или bearer token из формы.
  3. Откройте Как подключить и выберите свой клиент. Endpoint, transport и готовый JSON/TOML копируйте из UI: секрет после закрытия может больше не показываться.
  4. При регенерации старые credentials перестают работать; обновите клиент одним комплектом целиком.

Токен привязан к проекту и наследует права пользователя, который его выпустил. Legacy-подключение без пользователя остаётся read-only, пока его не перегенерируют.

Typed fields, server id и возвращаемая entity ​

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

Ошибка — часть recovery ​

Публичный tool не должен выбрасывать сырой exception. Ошибка возвращается envelope:

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. При error выполнить hint или показать пользователю конкретный выбор; не повторять тот же payload.

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

Внешней поверхности не выдаются внутренние training jobs, debug tokens и project bootstrap. Набор доступных инструментов может зависеть от роли, подключений и данных проекта. Инструкции по сущностям смотрите в Public REST manage как семантический близнец, но не копируйте REST-тело в MCP: DTO поверхностей физически разделены.

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