Перейти к основному содержимому

Интеграция MCP

Для модульных организаций подключённой организации необходим активный модуль CRM и области доступа, требуемые интеграцией. При недоступности CRM базовый API возвращает HTTP 403 с module_not_active. Перед повторной попыткой включите доступ к модулю в разделе Subscription; одной смены API-ключа недостаточно для устранения этой ошибки.

Scoutello предоставляет удалённый сервер Model Context Protocol (MCP) для контролируемого доступа к данным организации. Он использует те же интеграции, API-ключи, области доступа, проверки арендатора, ограничения частоты запросов и правила работы с записями, что и REST API Scoutello.

Используйте MCP, если AI-клиенту или агенту необходимо обнаруживать операции Scoutello и вызывать их как инструменты. Используйте REST, если приложению нужны стандартные HTTP-эндпоинты или сгенерированный клиент OpenAPI. Обе поверхности используют один и тот же базовый контракт данных.

Перед подключением​

Администратор организации должен создать интеграцию в разделе Настройки организации → Developer/API. При создании или ротации ключа:

  1. Выберите только те области доступа для чтения и записи, которые нужны MCP-клиенту.
  2. Сохраните полный sctl_api_ ключ, когда он будет показан. Scoutello отображает его только один раз.
  3. Храните ключ в секрете или конфигурации окружения MCP-клиента, а не в системе контроля версий.

Один и тот же ключ интеграции можно использовать для REST и MCP. Создавать отдельный ключ только для MCP не требуется и не рекомендуется. Ключи sctl_mcp_ прежнего формата не принимаются.

Параметры подключения​

Настройте клиент со следующими значениями:

Transport: Streamable HTTP
URL: https://admin.scoutello.com/api/v1/mcp
Header name: Authorization
Header value: Bearer YOUR_API_KEY

Замените YOUR_API_KEY сохранённым ключом интеграции. Форматы конфигурации клиентов различаются, но транспорт, URL и указанный выше HTTP-заголовок остаются неизменными. Если клиент не может установить Authorization, ключ можно передать вместо него в x-api-key. Не настраивайте оба заголовка.

Устаревший URL https://admin.scoutello.com/api/mcp сохраняется как псевдоним для совместимости. Для новых подключений используйте версионированный эндпоинт /api/v1/mcp.

Проверка подключения​

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

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

Инструменты и области доступа​

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

Область доступа APIИнструменты MCP
contacts.readcontacts_list, contacts_get, contacts_get_by_external_id
contacts.writecontacts_batch_upsert
tasks.readtasks_list, tasks_get, tasks_get_by_external_id
tasks.writetasks_batch_upsert
protocols.readprotocols_list, protocols_get, protocols_get_by_external_id
protocols.writeprotocols_batch_upsert
opportunities.readopportunities_list, opportunities_get, opportunities_get_by_external_id
opportunities.writeopportunities_batch_upsert
projects.readprojects_list, projects_get, projects_get_by_external_id
projects.writeprojects_batch_upsert (включая обновление данных участников)
milestones.readmilestones_list, milestones_get, milestones_get_by_external_id
milestones.writemilestones_batch_upsert
members.readmembers_list
events.readevents_list, events_get, events_get_by_external_id
events.writeevents_batch_upsert
mails.readmails_list, mails_get
mail-drafts.readmail_drafts_list, mail_drafts_get, mail_drafts_get_by_external_id
mail-drafts.writemail_drafts_batch_upsert (только для подготовки к проверке человеком)
tags.readtags_list

whoami всегда доступен аутентифицированному подключению. Входные данные инструментов и результаты используют те же схемы и оболочки ответов, что и связанные с ними REST-операции.

contacts_list принимает ограниченный search по имени, фамилии и названию компании, type, status и tagIds (массив из 1–50 идентификаторов, соответствующих любому выбранному тегу). Все поисковые токены должны совпадать с полем имени; все фильтры объединяются оператором AND. Передавайте эти фильтры на каждой странице курсора. Например, { "search": "Hamburg Hotel", "type": "company", "tagIds": ["tag-one", "tag-two"] } находит подходящие существующие аккаунты без полного сканирования всех данных.

Контакты CRM, не являющиеся участниками и связанные с учётной записью Scoutello, доступны для чтения и могут использоваться в ссылках, а поля членства и аккаунта остаются скрытыми, и редактирование контактов защищено. При обновлении только внешней ссылки можно зарегистрировать доступный для чтения контакт, используя externalId, его scoutelloId и необязательный externalUpdatedAt; не передавайте поля CRM. При последующих повторах запроса или обновлениях метаданных не передавайте scoutelloId. См. правила границ и связывания контактов.

Безопасная запись​

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

Установите mode в значение validate, чтобы выполнить сопоставление и проверку без записи данных. После проверки результатов повторите вызов с mode: "apply", чтобы принять корректные записи. MCP не поддерживает операции удаления.

Приостановка интеграции отклоняет запросы REST и MCP, использующие её ключи. Ротация заменяет её учётные данные, а отзыв навсегда отключает все учётные данные, принадлежащие интеграции.

Устранение неполадок​

РезультатЧто проверить
401 ошибка аутентификацииУбедитесь, что ключ указан полностью, а заголовок использует Bearer; ключ не должен быть заключён в кавычки.
403 ошибка авторизацииПредоставьте требуемую область действия, выполнив ротацию ключа интеграции, затем обновите клиент, указав новый ключ.
404 по URL MCPУбедитесь, что URL заканчивается на /api/v1/mcp. Сервис MCP может быть ещё не включён в этой среде Scoutello.
429 ошибка ограничения частоты запросовДождитесь указанного времени сброса и только после этого повторите запрос. REST и MCP используют одну квоту интеграции.
Инструмент отсутствуетПроверьте области действия ключа с помощью whoami; недоступные инструменты намеренно исключаются из списка обнаружения.

Сведения о полях записей, пагинации, пакетной обработке и конвертах ошибок см. в справочнике API Scoutello.

Планирование связанных проектов​

Создайте проект, затем его этапы, а после этого задачи и протоколы, используя стабильные внешние идентификаторы интеграции. Для доступа к новым этапам требуется milestones.read/milestones.write; предоставьте members.read, чтобы находить участников, которым можно назначать задачи. Права существующих учётных данных автоматически не расширяются. После ротации ключа или предоставления доступа обновите список инструментов и проверьте whoami.

Для assignedContacts проекта и этапа используйте идентификаторы Customer, а для assignedScoutelloUserIds задачи или ownerScoutelloUserId возможности — идентификаторы User. В ссылках на задачи и протоколы можно использовать projectScoutelloId или projectExternalId, а также эквивалентные пары для этапа и возможности. Ссылки только на этап позволяют определить проект; несоответствия отклоняют элемент пакета. Участники проекта добавляются или обновляются, а пропущенные записи сохраняются.

Протоколы поддерживают заметки по проекту или этапу без контакта, а также статус draft/final. Импорт связанных рабочих данных выполняется без уведомлений и никогда не отправляет сообщения. Инструменты списка предоставляют те же фильтры по проекту, статусу, назначению и сроку выполнения для конкретной сущности, что и REST. Передавайте точные фильтры, включая updatedSince, на каждой странице курсора. Полный контракт и семантику значений null и пропущенных полей см. в справочнике API.

Проверяйте каждый зависимый пакет, применяйте его, анализируйте каждый результат и считывайте записи обратно, прежде чем считать заполнение завершённым. Тестовый запуск не может разрешить связи с родительскими объектами, существующими только в другом тестовом запуске. При повторной попытке неоднозначной исходной ссылки с использованием scoutelloId сначала выполните поиск по внешнему идентификатору; идентификаторы начальной загрузки нельзя повторно использовать после создания ссылки.

Инструкции агенту по проектам продаж​

Каждый контакт, созданный или повторно использованный для проекта продаж, должен явно ссылаться на этот проект с помощью projectScoutelloId или projectExternalId в contacts_batch_upsert. Упоминание проекта в заметках или внешнем идентификаторе не означает участия в проекте. Для записи контактов со ссылками на проект также требуется projects.write. Считайте контакт обратно с помощью contacts.read и projects.read и проверьте projectParticipations; сохраняйте существующие членства и группы. Для общих контактов, не относящихся к проекту, ссылка на проект не требуется.

Храните компании и подтверждённых людей как отдельные контакты. Связывайте человека с компанией с помощью companyScoutelloId или companyExternalId, а не только с помощью companyName. Изменения контакта, связи с компанией и членства выполняются атомарно для каждого элемента пакета; недействительные ссылки не оставляют частично созданный контакт. Не выдумывайте людей и не добавляйте теги происхождения данных.

Готовьте исходящие электронные письма с помощью mail_drafts_batch_upsert, а не в виде тел протоколов. Явно предоставьте новые области действия mail-drafts.read и mail-drafts.write; для подготовки также требуются contacts.read и projects.write. Существующие учётные данные автоматически не получают новые разрешения. Используйте стабильный внешний идентификатор, expectedVersion: 0 для создания, явные ссылки на проект и контакт, идентификатор User утверждённого согласующего, а также настроенную область отправителя organization или personal. Никогда не угадывайте адрес получателя или конфигурацию отправителя.

Храните результаты исследования в content.notes; только content.subject и content.body являются исходящим текстом. Создание черновика гарантирует, что контакт станет участником проекта. Для обновлений используйте версию, возвращённую при последнем чтении; проверенные или отправленные черновики нельзя редактировать. Идентичные повторные запросы возвращают исходный черновик, не создавая новую проверку. Считайте обратно его reviewUrl, draftVersion, contentHash, статус согласования/отправки и итоговый mailScoutelloId.

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

Подготовка публикаций в социальных сетях​

Предоставляйте social-channels.read, social-posts.read, social-post-drafts.read и social-post-drafts.write по мере необходимости. members_list (members.read) может находить идентификаторы пользователей-рецензентов. Социальные инструменты отображаются только при предоставлении соответствующей области доступа:

Область доступаИнструменты
social-channels.readsocial_channels_list
social-posts.readsocial_posts_list, social_posts_get
social-post-drafts.readsocial_post_drafts_list, social_post_drafts_get, social_post_drafts_get_by_external_id
social-post-drafts.writesocial_post_drafts_batch_upsert, social_media_create_upload, social_media_finalize_upload

Ознакомьтесь с возможностями каналов и историей, созданной Scoutello, загрузите материалы, а затем отправьте полные варианты для каналов с указанием рецензента. Инструменты загрузки возвращают инструкции HTTP PUT: передайте исходные байты файла вне MCP, затем завершите загрузку с помощью { "assetId": "..." }. Не встраивайте файлы в формате base64 в аргументы инструментов.

Используйте expectedVersion: 0 для новых черновиков, а для ожидающих изменений — текущую версию. mode: "validate" не выполняет операций записи. Инструмент возвращает URL для проверки; только пользователь панели управления может одобрить публикацию или планирование. Инструмента MCP для одобрения, публикации, отмены или удаления публикации не существует. Проверяйте инструменты черновиков и истории, чтобы отслеживать одобрение, причины отклонения и результаты доставки по каждому каналу. Для проверенных черновиков при отправке новых предложений требуется новый внешний идентификатор.

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