Интеграция 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. При создании или ротации ключа:
- Выберите только те области доступа для чтения и записи, которые нужны MCP-клиенту.
- Сохраните полный
sctl_api_ключ, когда он будет показан. Scoutello отображает его только один раз. - Храните ключ в секрете или конфигурации окружения 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.read | contacts_list, contacts_get, contacts_get_by_external_id |
contacts.write | contacts_batch_upsert |
tasks.read | tasks_list, tasks_get, tasks_get_by_external_id |
tasks.write | tasks_batch_upsert |
protocols.read | protocols_list, protocols_get, protocols_get_by_external_id |
protocols.write | protocols_batch_upsert |
opportunities.read | opportunities_list, opportunities_get, opportunities_get_by_external_id |
opportunities.write | opportunities_batch_upsert |
projects.read | projects_list, projects_get, projects_get_by_external_id |
projects.write | projects_batch_upsert (включая обновление данных участников) |
milestones.read | milestones_list, milestones_get, milestones_get_by_external_id |
milestones.write | milestones_batch_upsert |
members.read | members_list |
events.read | events_list, events_get, events_get_by_external_id |
events.write | events_batch_upsert |
mails.read | mails_list, mails_get |
mail-drafts.read | mail_drafts_list, mail_drafts_get, mail_drafts_get_by_external_id |
mail-drafts.write | mail_drafts_batch_upsert (только для подготовки к проверке человеком) |
tags.read | tags_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.read | social_channels_list |
social-posts.read | social_posts_list, social_posts_get |
social-post-drafts.read | social_post_drafts_list, social_post_drafts_get, social_post_drafts_get_by_external_id |
social-post-drafts.write | social_post_drafts_batch_upsert, social_media_create_upload, social_media_finalize_upload |
Ознакомьтесь с возможностями каналов и историей, созданной Scoutello, загрузите материалы, а затем отправьте полные варианты для каналов с указанием рецензента. Инструменты загрузки возвращают инструкции HTTP PUT: передайте исходные байты файла вне MCP, затем завершите загрузку с помощью { "assetId": "..." }. Не встраивайте файлы в формате base64 в аргументы инструментов.
Используйте expectedVersion: 0 для новых черновиков, а для ожидающих изменений — текущую версию. mode: "validate" не выполняет операций записи. Инструмент возвращает URL для проверки; только пользователь панели управления может одобрить публикацию или планирование. Инструмента MCP для одобрения, публикации, отмены или удаления публикации не существует. Проверяйте инструменты черновиков и истории, чтобы отслеживать одобрение, причины отклонения и результаты доставки по каждому каналу. Для проверенных черновиков при отправке новых предложений требуется новый внешний идентификатор.
См. раздел публикации в социальных сетях для проверки человеком, где приведены примеры входных данных, ограничения загрузки, правила пагинации и сведения о проверках, выполненных с опозданием.