MCP інтеграція
Для модульних організацій підключена організація повинна мати активний модуль CRM, а також необхідні для інтеграції області доступу. Базовий API повертає HTTP 403 із module_not_active, якщо доступ до CRM недоступний. Надайте доступ до модуля в розділі 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, доступні для читання та використання як посилання, тоді як поля членства й облікового запису залишаються прихованими, а редагування контактів захищене. Операція upsert лише із зовнішнім посиланням може зареєструвати доступний для читання контакт за допомогою externalId, його scoutelloId і необов’язкового externalUpdatedAt; не передавайте поля CRM. Під час подальших повторних спроб або оновлень метаданих не передавайте scoutelloId. Див. правила меж доступу до контактів і зв’язування.
Безпечний запис
Інструменти пакетного upsert можуть негайно змінювати дані 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 для схвалення, публікації, скасування чи видалення допису. Перевіряйте інструменти чернеток та історії
щодо схвалення, причин відхилення й результатів доставки для кожного каналу. Для подальших пропозицій перевірені чернетки
потребують нового зовнішнього ідентифікатора.
Приклади вхідних даних, обмеження на завантаження, пагінацію та обробку запізнілих перевірок див. у матеріалі дописи в соціальних мережах для перевірки людиною.