Přeskočit na hlavní obsah

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:

  1. Vyberte pouze rozsahy oprávnění pro čtení a zápis, které klient MCP potřebuje.
  2. Po zobrazení uložte celý klíč sctl_api_. Scoutello ho zobrazí pouze jednou.
  3. 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 APINástroje 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 (včetně aktualizací účastníků)
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 (pouze k přípravě na kontrolu člověkem)
tags.readtags_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ýsledekCo 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 autorizaceUdělte požadovaný rozsah otočením integračního klíče a poté aktualizujte klienta náhradním klíčem.
404 na URL MCPOvěř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:

RozsahNástroje
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

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.