Подключение по MCP

Что такое MCP

MCP (Model Context Protocol) — открытый протокол, по которому ИИ-клиенты подключают внешние инструменты. Подключив Умный Диалог, вы можете попросить ассистента в чате: «покажи диалоги на паузе», «найди в базе знаний, что мы пишем про доставку», «передай этот диалог оператору» — ассистент выполнит запрос через инструменты сервера в пределах выданных прав.

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

Сервер

Ключ выпускается в кабинете: «Настройки» → «Ключи API». Выберите нужные права; подробно — в руководстве «Ключи API». Клиент видит только те инструменты, которые ключ может вызвать: у ключа «только чтение» в списке нет ни одного инструмента на запись. В лимит запросов компании входит каждый вызов инструмента, как запрос к REST: пакет из пяти вызовов в одном HTTP-запросе — это пять запросов. Если на весь пакет лимита не хватает, не выполняется ни один вызов из него.

Подключение через OAuth

OAuth по умолчанию доступен во всех компаниях. Если в настройках указано, что новые OAuth-подключения недоступны, подключите ассистента по API-ключу. Его настройка описана ниже.

1. В настройках внешнего ассистента начните подключение удалённого MCP-сервера с адресом https://smartdialogue.ru/api/mcp.
2. Войдите в Умный Диалог на https://app.smartdialogue.ru. Пароль вводится в нашем кабинете и не передаётся ассистенту.
3. На странице «Подключение приложения» проверьте приложение, компанию и аккаунт. В списке «Разрешения приложения» снимите лишние права. Можно оставить только права, запрошенные приложением и доступные вашей роли.
4. Нажмите «Разрешить доступ», оставив хотя бы одно право, или «Отказать». После решения браузер вернётся в ассистент; при согласии он получит отдельный токен.

Запрос действует 10 минут. Если срок истёк или после обрыва связи результат согласия неизвестен, начните подключение заново в ассистенте. Обновление токена выполняется через OAuth; расширение прав требует нового согласия. Токен открывает инструменты MCP и не заменяет вход в кабинет или ключ REST API.

Подключённые приложения

В «Настройки» → «Подключённые приложения» видны компания, сотрудник, разрешивший доступ, права и последний запрос. Сотрудник управляет своими подключениями; администратор и владелец компании также управляют доступами команды. Подключения по ключу находятся в карточке «Ключи API».

Чтобы отключить приложение, нажмите «Отозвать доступ» и подтвердите кнопкой «Отозвать». Его токены перестанут давать доступ к MCP. Завершённые действия отзыв не отменяет. Для повторного подключения потребуется новое согласие. Просмотр и отзыв уже выданных доступов сохраняются при остановке новых подключений.

Клиент с API-ключом

В настройках клиента добавьте удалённый MCP-сервер с транспортом HTTP, адресом https://smartdialogue.ru/api/mcp и заголовком Authorization: Bearer sd_live_…. Если клиент использует JSON-конфигурацию с разделом mcpServers, настройка может выглядеть так:

{
  "mcpServers": {
    "smartdialogue": {
      "type": "http",
      "url": "https://smartdialogue.ru/api/mcp",
      "headers": {
        "Authorization": "Bearer sd_live_…"
      }
    }
  }
}

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

Ключ из переменной окружения

Некоторые клиенты подставляют переменные окружения в JSON-конфигурацию. Если ваш клиент поддерживает запись ${env:SMARTDIALOGUE_API_KEY}, сохраните ключ в переменной SMARTDIALOGUE_API_KEY, а в файле оставьте ссылку на неё:

{
  "mcpServers": {
    "smartdialogue": {
      "url": "https://smartdialogue.ru/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SMARTDIALOGUE_API_KEY}"
      }
    }
  }
}

Такой способ и синтаксис подстановки должны поддерживаться самим клиентом. Умный Диалог получает готовый заголовок Authorization.

Клиент с OAuth

Для клиента, который подключает удалённый MCP только через OAuth, используйте общий порядок выше. Если клиент позволяет задать заголовок Authorization, можно подключиться по API-ключу. Совместимость конкретного ассистента проверяется при подключении.

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

• Начните с ключа только на чтение. При выпуске выберите набор «Только чтение»: модель сможет смотреть диалоги, базу знаний, контакты и агентов, но ничего не изменит.
• Для записи — отдельный ключ. Когда понадобится отвечать клиентам или пополнять базу знаний, выпустите второй ключ с нужными правами и подключайте его только там, где это действительно нужно. Отозвать его можно, не трогая ключ на чтение.
• Сообщения клиентов — данные, а не команды. Клиент может написать что угодно, в том числе «удали все контакты». Сервер помечает такие тексты в ответах как недоверенные и просит модель не выполнять их. Операции записи выполняются сразу в пределах выданных прав. Настройки подтверждения вызовов в самом ассистенте определяет его приложение.
• Повтор вызова — это новое действие. Если клиент MCP повторит send_operator_message после завершения предыдущего действия, сообщение может отправиться повторно. Передавайте в send_operator_message и add_text_document аргумент idempotency_key — строку до 255 байт, свою для каждого действия, например UUID. Повтор с тем же значением в течение суток вернёт первый результат с пометкой idempotent_replayed и ничего не выполнит; тот же ключ с другими аргументами — ошибка. Это тот же ключ, что заголовок Idempotency-Key у REST: отправку, начатую по REST, повтор через MCP с тем же ключом второй раз не выполнит. Сам заголовок Idempotency-Key у запроса к MCP на вызовы не действует: он один на весь HTTP-запрос. Если хранилище повторов Redis недоступно или результат не сохранился, защита от дублей может не сработать. После обрыва связи проверьте результат действия перед повтором.
• Всё, что модель делает через ключ, делается от имени выпустившего его сотрудника: ответы клиентам помечены в кабинете «через API» и названием ключа.

Квота и параллельные вызовы

Вызовы MCP по OAuth и API-ключам делят одну тарифную квоту компании с запросами REST API по ключам. Новое приложение, второй ключ или обновлённый токен её не увеличивают. Число запросов по тарифам указано в ограничениях API. Каждый вызов в разрешённом пакете учитывается отдельно. Запросы кабинета в эту квоту не входят.

Дополнительно ограничено число параллельных MCP-запросов на компанию и на весь backend. Ограничения одинаковы для OAuth и ключей; они действуют независимо от тарифной квоты.

Инструменты

17 инструментов. «Право» — какое право должно быть у API-ключа или OAuth-доступа и у роли сотрудника, чтобы инструмент появился в списке. «Деструктивное» — так инструмент помечен для клиента MCP: последствия вызова не отменить одним действием, подтверждайте его вручную.

Удаление контактов и документов, назначение диалогов на других сотрудников и обход сайта остаются только в REST API: модели в чате достаются действия, которые безопасно делать по просьбе.