Integrace MCP
U modulárních organizací musí mít připojená organizace aktivní modul CRM a také požadované rozsahy oprávnění integrace. Základní API vrací HTTP 403 s module_not_active, pokud není přístup k CRM k dispozici. Před opakováním požadavku vyřešte přístup k modulu v části Předplatné; samotná změna klíče API tuto chybu neodstraní.
Scoutello poskytuje vzdálený server Model Context Protocol (MCP) pro řízený přístup k datům organizace. Používá stejné integrace, klíče API, rozsahy oprávnění, kontroly tenanta, limity rychlosti a chování záznamů jako REST API Scoutello.
MCP použijte, pokud má AI klient nebo agent vyhledávat operace Scoutello a volat je jako nástroje. REST použijte, pokud aplikace potřebuje běžné HTTP endpointy nebo vygenerovaného klienta OpenAPI. Obě rozhraní používají stejný základní datový kontrakt.
Před připojením
Administrátor organizace musí vytvořit integraci v části Nastavení organizace → Vývojář/API. Při vytváření nebo obnově jejího klíče:
- Vyberte pouze rozsahy oprávnění pro čtení a zápis, které klient MCP potřebuje.
- Po zobrazení uložte celý klíč
sctl_api_. Scoutello ho zobrazí pouze jednou. - Uložte klíč do tajné konfigurace nebo konfigurace prostředí klienta MCP, nikoli do systému pro správu zdrojového kódu.
Stejný integrační klíč lze použít pro REST i MCP. Vytvoření druhého klíče určeného pouze pro MCP není nutné ani doporučené. Starší klíče sctl_mcp_ nejsou přijímány.
Údaje pro připojení
Nakonfigurujte klienta pomocí těchto údajů:
Transport: Streamable HTTP
URL: https://admin.scoutello.com/api/v1/mcp
Header name: Authorization
Header value: Bearer YOUR_API_KEY
Nahraďte YOUR_API_KEY uloženým integračním klíčem. Formáty konfigurace klientů se liší, ale transport, URL a výše uvedená hlavička HTTP zůstávají stejné. Pokud klient nemůže nastavit Authorization, může klíč místo toho odeslat v x-api-key. Nenastavujte obě hlavičky.
Starší URL https://admin.scoutello.com/api/mcp zůstává aliasem pro zachování kompatibility. Nová připojení by měla používat verzovaný endpoint /api/v1/mcp.
Ověření připojení
Po připojení klienta nejprve zavolejte nástroj whoami. Vrací aktuální integraci a organizaci, informace o vypršení platnosti a využití přihlašovacích údajů, stav limitu požadavků a udělené rozsahy, aniž by odhaloval záznamy organizace.
Pokud whoami identifikuje neočekávanou organizaci nebo integraci, odpojte klienta a opravte jeho klíč, než zavoláte jiný nástroj.
Nástroje a rozsahy
Server MCP nabízí pouze nástroje udělené aktuálnímu klíči. Klient nemůže objevit ani volat nástroj pro zápis pouze s odpovídajícím rozsahem pro čtení.
| Rozsah API | Nástroje 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 (včetně aktualizací účastníků) |
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 (pouze k přípravě na kontrolu člověkem) |
tags.read | tags_list |
whoami je pro ověřené připojení vždy dostupný. Vstupy a výsledky nástrojů používají stejná schémata a obálky odpovědí jako související operace REST.
contacts_list přijímá omezený search podle jmen, type, status a tagIds (pole 1–50 ID odpovídajících libovolnému vybranému štítku). Všechny vyhledávací výrazy se musí shodovat s polem jména; všechny filtry se kombinují pomocí AND. Tyto filtry používejte na každé stránce kurzoru. Například { "search": "Hamburg Hotel", "type": "company", "tagIds": ["tag-one", "tag-two"] } vyhledá odpovídající existující účty bez procházení celého inventáře.
Kontakty z CRM, které nejsou členy a jsou propojené s přihlášením Scoutello, lze číst a odkazovat na ně, zatímco členská a účetní pole zůstávají skrytá a úpravy kontaktů jsou chráněné. Upsert pouze s externím odkazem může zaregistrovat čitelný kontakt pomocí externalId, jeho scoutelloId a volitelného externalUpdatedAt; všechna pole CRM vynechte. Při pozdějších opakovaných pokusech nebo aktualizacích metadat vynechte scoutelloId. Viz hranice kontaktů a pravidla propojování.
Bezpečný zápis
Nástroje pro hromadný upsert mohou okamžitě měnit data ve Scoutello. Pro stejnou integraci a externí ID jsou idempotentní, přesto by před použitím změn měly být zkontrolovány zamýšlený zdroj, organizace a rozsah.
Nastavte mode na validate, aby proběhlo párování a ověření bez zápisu. Po kontrole výsledků opakujte volání s mode: "apply" a přijměte platné záznamy. MCP neposkytuje operace pro mazání.
Pozastavení integrace odmítne požadavky REST i MCP používající její klíče. Otočení klíče nahradí její přihlašovací údaj a odvolání trvale deaktivuje všechny přihlašovací údaje patřící integraci.
Řešení problémů
| Výsledek | Co zkontrolovat |
|---|---|
401 chyba ověřování | Ověřte, že je přítomen celý klíč a že hlavička používá Bearer; kolem klíče nesmí být uvozovky. |
403 chyba autorizace | Udělte požadovaný rozsah otočením integračního klíče a poté aktualizujte klienta náhradním klíčem. |
404 na URL MCP | Ověřte, že URL končí na /api/v1/mcp. Služba MCP v daném prostředí Scoutello ještě nemusí být povolena. |
429 chyba limitu požadavků | Před opakováním počkejte do vráceného času resetování. REST a MCP využívají stejný integrační limit. |
| Nástroj chybí | Zkontrolujte rozsahy klíče pomocí whoami; nedostupné nástroje jsou z objevování záměrně vynechány. |
Informace o polích záznamů, stránkování, hromadném zpracování a obálkách chyb najdete v referenční dokumentaci API Scoutello.
Plánování propojeného projektu
Vytvořte projekt, poté jeho milníky a následně úkoly a protokoly pomocí stabilních externích ID pro integraci. Nový přístup k milníkům vyžaduje milestones.read/milestones.write; pro vyhledání přiřaditelných členů udělte members.read. Stávající přihlašovací údaje se automaticky nerozšiřují. Po rotaci nebo udělení přístupu obnovte zjišťování nástrojů a zkontrolujte whoami.
Pro projekt/mílíník assignedContacts používejte ID zákazníků členů a pro úkol assignedScoutelloUserIds nebo příležitost ownerScoutelloUserId ID uživatelů. Reference úkolů/protokolů přijímají projectScoutelloId nebo projectExternalId a také odpovídající dvojice milník/příležitost. Odkazy obsahující pouze milník odvodí projekt; nesrovnalosti položku dávky odmítnou. Účastníci projektu se přidávají nebo aktualizují a vynechané záznamy zůstávají zachovány.
Protokoly podporují poznámky k projektům a milníkům bez kontaktu a stav draft/final. Importy této propojené práce probíhají bez upozornění a nikdy neodesílají komunikaci. Nástroje pro výpis poskytují stejné filtry specifické pro danou entitu — projekt, stav, přiřazení a termín — jako REST. Přenášejte přes každou stránku kurzoru přesné filtry včetně updatedSince. Úplný kontrakt a sémantiku hodnot null/vynechaných hodnot najdete v referenci API.
Každou závislou dávku ověřte, aplikujte ji, zkontrolujte každý výsledek a před považováním naplnění za dokončené záznamy znovu načtěte. Zkušební běh nemůže vyřešit nadřazené záznamy, které existují pouze v jiném zkušebním běhu. Při opakování nejednoznačného počátečního odkazu pomocí scoutelloId nejprve načtěte záznam podle externího ID; bootstrapová ID nelze po vytvoření odkazu znovu použít.
Pokyny pro agenta prodejních projektů
Každý kontakt vytvořený nebo znovu použitý pro prodejní projekt musí tento projekt explicitně uvádět pomocí projectScoutelloId nebo projectExternalId v contacts_batch_upsert. Zmínka projektu v poznámkách nebo externím ID nepředstavuje členství. Zápisy kontaktů s odkazy na projekty vyžadují také projects.write. Kontakt znovu načtěte pomocí contacts.read a projects.read a ověřte projectParticipations; zachovejte stávající členství a skupiny. Obecné kontakty mimo projekt odkaz na projekt nevyžadují.
Společnosti a ověřené osoby udržujte jako samostatné kontakty. Osobu ke společnosti propojte pomocí companyScoutelloId nebo companyExternalId, nikoli pouze pomocí companyName. Změny kontaktu, vztahu se společností a členství jsou atomické pro každou položku dávky; neplatné odkazy nezanechají částečně vytvořený kontakt. Nevymýšlejte osoby ani nepřidávejte značky původu.
Odchozí e-maily připravujte pomocí mail_drafts_batch_upsert, nikdy jako těla protokolů. Nové rozsahy mail-drafts.read a mail-drafts.write udělujte explicitně; příprava vyžaduje také contacts.read a projects.write. Stávající přihlašovací údaje automaticky nezískají nová oprávnění. Použijte stabilní externí ID, expectedVersion: 0 pro vytvoření, explicitní odkazy na projekt/kontakt, ID uživatele schváleného schvalovatele a nakonfigurovaný rozsah odesílatele organization nebo personal. Nikdy neodhadujte adresu příjemce ani konfiguraci odesílatele.
Výzkum uchovávejte v content.notes; pouze content.subject a content.body představují odchozí text. Vytvoření konceptu zajistí, že kontakt bude účastníkem projektu. Aktualizace musí používat verzi vrácenou při posledním načtení; u zkontrolovaných nebo odeslaných konceptů jsou úpravy odmítnuty. Totožná opakování vrátí původní koncept, aniž by vytvořila další kontrolu. Znovu načtěte jeho reviewUrl, draftVersion, contentHash, stav schválení/odeslání a následný mailScoutelloId.
Schvalovat a odesílat prostřednictvím stávající obrazovky kontroly může pouze přiřazená osoba. Integrace nemohou schvalovat, distribuovat ani odesílat, ani s přístupem k zápisu konceptů. Při převodu starých konceptů zachovejte původní protokoly a na náhrady uveďte křížové odkazy. Selhání doručení ve frontě nebo nejednoznačná selhání vyžadují prověření, nikdy slepé opětovné odeslání.
Příprava příspěvků na sociální sítě
Podle potřeby udělte social-channels.read, social-posts.read, social-post-drafts.read a
social-post-drafts.write. members_list (members.read) může vyhledat
ID uživatelů kontrolujících osob. Nástroje pro sociální sítě jsou nabízeny pouze při udělení příslušného rozsahu:
| Rozsah | Nástroje |
|---|---|
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 |
Načtěte možnosti kanálu a historii vytvořenou v Scoutello, nahrajte podklady a poté odešlete kompletní varianty kanálů s uvedením kontrolující osoby. Nástroje pro nahrávání vracejí pokyny HTTP PUT: přeneste původní bajty souboru mimo MCP a poté nahrávání dokončete pomocí { "assetId": "..." }. Nevkládejte soubory zakódované v base64 do argumentů nástrojů.
Pro nové koncepty použijte expectedVersion: 0 a pro čekající revize aktuální verzi. mode: "validate" neprovádí žádné zápisy. Nástroj vrací URL kontroly; publikování nebo naplánování může schválit pouze osoba používající řídicí panel. Neexistuje žádný nástroj MCP pro schválení, publikování, zrušení ani smazání příspěvku. Pomocí nástrojů pro koncepty/historii sledujte schválení, důvody zamítnutí a výsledky doručení pro jednotlivé kanály. Zkontrolované koncepty vyžadují pro další návrhy nové externí ID.
Příklady vstupů, limity nahrávání, stránkování a chování při pozdní kontrole najdete v části sociální příspěvky ke kontrole člověkem.