Preskočiť na hlavný obsah

Integrácia MCP

V prípade modulárnych organizácií musí mať pripojená organizácia aktívny modul CRM a požadované rozsahy integrácie. Základné API vracia HTTP 403 s module_not_active, ak prístup k CRM nie je dostupný. Pred opakovaním požiadavky vyriešte prístup k modulu v časti Predplatné; samotná zmena kľúča API túto chybu neopraví.

Scoutello poskytuje vzdialený server Model Context Protocol (MCP) na riadený prístup k údajom organizácie. Používa rovnaké integrácie, kľúče API, rozsahy, kontroly tenanta, limity požiadaviek a správanie záznamov ako REST API Scoutello.

MCP použite vtedy, keď má klient alebo agent s umelou inteligenciou objavovať operácie Scoutello a volať ich ako nástroje. REST použite vtedy, keď aplikácia potrebuje štandardné HTTP endpointy alebo vygenerovaného klienta OpenAPI. Obe rozhrania používajú rovnaký základný dátový kontrakt.

Pred pripojením​

Správca organizácie musí vytvoriť integráciu v časti Nastavenia organizácie → Vývojár/API. Pri vytváraní alebo rotácii kľúča:

  1. Vyberte iba rozsahy na čítanie a zápis, ktoré klient MCP potrebuje.
  2. Po zobrazení uložte celý kľúč sctl_api_. Scoutello ho zobrazí iba raz.
  3. Uložte kľúč do tajnej alebo environmentálnej konfigurácie klienta MCP, nie do zdrojového kódu.

Rovnaký integračný kľúč možno použiť na volania REST aj MCP. Vytvorenie druhého kľúča určeného iba pre MCP nie je potrebné ani odporúčané. Staršie kľúče sctl_mcp_ sa neprijímajú.

Hodnoty pripojenia​

Nakonfigurujte klienta pomocou týchto hodnôt:

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 kľúčom. Formáty konfigurácie klientov sa líšia, no transport, URL a hlavička HTTP uvedené vyššie zostávajú rovnaké. Ak klient nedokáže nastaviť Authorization, môže namiesto toho odoslať kľúč v x-api-key. Nenastavujte obe hlavičky.

Staršia URL https://admin.scoutello.com/api/mcp zostáva kompatibilným aliasom. Nové pripojenia by mali používať verzovaný endpoint /api/v1/mcp.

Overenie pripojenia​

Po pripojení klienta najskôr zavolajte nástroj whoami. Vráti aktuálnu integráciu a organizáciu, informácie o platnosti a používaní poverení, stav limitov požiadaviek a udelené rozsahy bez odhalenia záznamov organizácie.

Ak whoami identifikuje neočakávanú organizáciu alebo integráciu, odpojte klienta a pred zavolaním ďalšieho nástroja opravte jeho kľúč.

Nástroje a rozsahy​

Server MCP ponúka iba nástroje udelené aktuálnym kľúčom. Klient nemôže objaviť ani zavolať nástroj na zápis, ak má udelený iba príslušný rozsah na čítanie.

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 (vrátane upsertov účastníkov)
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 (iba na prípravu na kontrolu osobou)
tags.readtags_list

whoami je vždy dostupný pre autentifikované pripojenie. Vstupy a výsledky nástrojov používajú rovnaké schémy a obálky odpovedí ako príslušné operácie REST.

contacts_list prijíma obmedzený search v poliach krstného mena, priezviska a názvu spoločnosti, type, status a tagIds (pole s 1 až 50 ID, ktoré zodpovedajú ľubovoľnej vybratej značke). Všetky vyhľadávacie tokeny sa musia zhodovať s poľom názvu; všetky filtre sa kombinujú pomocou AND. Tieto filtre zachovajte pri každej stránke kurzora. Napríklad { "search": "Hamburg Hotel", "type": "company", "tagIds": ["tag-one", "tag-two"] } nájde zhodujúce sa existujúce účty bez prehľadávania celého inventára.

Kontakty CRM, ktoré nie sú členmi a sú prepojené s prihlásením do Scoutello, možno čítať a odkazovať na ne, zatiaľ čo členské a účtové polia zostávajú skryté a úpravy kontaktov sú chránené. Upsert iba s externým odkazom môže zaregistrovať čitateľný kontakt pomocou externalId, jeho scoutelloId a voliteľného externalUpdatedAt; vynechajte všetky polia CRM. Pri neskorších opakovaniach alebo aktualizáciách metadát vynechajte scoutelloId. Pozrite si pravidlá hraníc kontaktov a prepájania.

Bezpečný zápis​

Nástroje na hromadné upsertovanie môžu okamžite zmeniť údaje v Scoutello. Pre rovnakú integráciu a externé ID sú idempotentné, no pred použitím zmien by volajúce strany mali skontrolovať zamýšľaný zdroj, organizáciu a rozsah.

Nastavte mode na validate, aby sa spustilo porovnávanie a overenie bez zápisu. Po kontrole výsledkov zopakujte volanie s hodnotou mode: "apply" a prijmite platné záznamy. MCP neposkytuje operácie odstránenia.

Pozastavenie integrácie zamietne požiadavky REST aj MCP používajúce jej kľúče. Rotácia nahradí jej prihlasovací údaj a odvolanie natrvalo deaktivuje všetky prihlasovacie údaje patriace integrácii.

Riešenie problémov​

VýsledokČo skontrolovať
401 chyba autentifikácieSkontrolujte, či je uvedený celý kľúč a či hlavička používa Bearer, bez úvodzoviek okolo kľúča.
403 chyba autorizácieUdeľte požadovaný rozsah rotáciou kľúča integrácie a potom aktualizujte klienta náhradným kľúčom.
404 na URL MCPSkontrolujte, či URL končí na /api/v1/mcp. Služba MCP ešte nemusí byť v danom prostredí Scoutello povolená.
429 chyba prekročenia limitu požiadaviekPred opakovaním počkajte na vrátený čas obnovenia limitu. REST a MCP využívajú rovnakú kvótu integrácie.
Nástroj chýbaSkontrolujte rozsahy kľúča pomocou whoami; nedostupné nástroje sú zo zisťovania zámerne vynechané.

Informácie o poliach záznamov, stránkovaní, hromadnom správaní a obálkach chýb nájdete v referencii API Scoutello.

Prepojené plánovanie projektov​

Vytvorte projekt, potom jeho míľniky a následne úlohy a protokoly pomocou stabilných externých ID integrácie. Prístup k novým míľnikom vyžaduje milestones.read/milestones.write; na vyhľadávanie priraditeľných členov udeľte members.read. Existujúce prihlasovacie údaje sa automaticky nerozšíria. Po rotácii alebo udelení prístupu obnovte zisťovanie nástrojov a skontrolujte whoami.

Pre assignedContacts projektu alebo míľnika použite ID zákazníka člena a pre assignedScoutelloUserIds úlohy alebo ownerScoutelloUserId príležitosti použite ID používateľa. Odkazy na úlohy alebo protokoly akceptujú projectScoutelloId alebo projectExternalId, ako aj zodpovedajúce dvojice míľnika alebo príležitosti. Odkazy obsahujúce iba míľnik určia projekt automaticky; nesúlad zamietne položku hromadnej operácie. Účastníci projektu sa upsertujú aditívne a vynechané položky zostanú zachované.

Protokoly podporujú poznámky k projektom alebo míľnikom bez kontaktu a stav draft/final. Importy tejto prepojenej práce sú tiché a nikdy neodosielajú komunikáciu. Nástroje na zoznamy poskytujú rovnaké filtre projektov, stavov, priradení a termínov špecifické pre danú entitu ako REST. Presné filtre vrátane updatedSince prenášajte cez každú stránku kurzora. Úplný kontrakt a sémantiku hodnôt null alebo vynechaných hodnôt nájdete v referencii API.

Overte každú závislú hromadnú operáciu, použite ju, skontrolujte každý výsledok a pred označením naplnenia za dokončené si záznamy znova načítajte. Testovacie spustenie nedokáže vyriešiť nadradené záznamy, ktoré existujú iba v inom testovacom spustení. Pri opakovaní nejednoznačného počiatočného prepojenia pomocou scoutelloId najprv vyhľadajte záznam podľa externého ID; zavádzacie ID nemožno po vytvorení prepojenia znova použiť.

Pokyny pre agenta predajných projektov​

Každý kontakt vytvorený alebo znovu použitý pre predajný projekt musí tento projekt explicitne uvádzať pomocou projectScoutelloId alebo projectExternalId v contacts_batch_upsert. Uvedenie projektu v poznámkach alebo externom ID nepredstavuje členstvo. Zápisy kontaktov s odkazmi na projekt vyžadujú aj projects.write. Načítajte kontakt znova pomocou contacts.read a projects.read a overte projectParticipations; zachovajte existujúce členstvá a skupiny. Všeobecné kontakty mimo projektu odkaz na projekt nevyžadujú.

Spoločnosti a overené osoby uchovávajte ako samostatné kontakty. Osobu prepojte so spoločnosťou pomocou companyScoutelloId alebo companyExternalId, nielen pomocou companyName. Zmeny kontaktu, vzťahu so spoločnosťou a členstva sú atómové pre každú položku hromadnej operácie; neplatné odkazy nezanechajú čiastočne vytvorený kontakt. Nevymýšľajte osoby ani nepridávajte značky pôvodu.

Odchádzajúce e-maily pripravujte pomocou mail_drafts_batch_upsert, nikdy nie ako telá protokolov. Nové rozsahy mail-drafts.read a mail-drafts.write udeľte explicitne; príprava vyžaduje aj contacts.read a projects.write. Existujúce prihlasovacie údaje automaticky nezískajú nové oprávnenia. Použite stabilné externé ID, expectedVersion: 0 na vytvorenie, explicitné odkazy na projekt alebo kontakt, ID používateľa schvaľovateľa, ktorý schválenie prijal, a nakonfigurovaný rozsah odosielateľa organization alebo personal. Nikdy nehádajte adresu príjemcu ani konfiguráciu odosielateľa.

Výskum uchovávajte v content.notes; odchádzajúci text obsahujú iba content.subject a content.body. Vytvorenie konceptu zabezpečí, že kontakt je účastníkom projektu. Aktualizácie musia používať verziu vrátenú pri poslednom načítaní; skontrolované alebo odoslané koncepty úpravy zamietnu. Identické opakovania vrátia pôvodný koncept bez vytvorenia ďalšieho schválenia. Znova načítajte jeho reviewUrl, draftVersion, contentHash, stav schválenia alebo odoslania a výsledný mailScoutelloId.

Schvaľovať a odosielať prostredníctvom existujúcej obrazovky kontroly môže iba priradená osoba. Integrácie nemôžu schvaľovať, distribuovať ani odosielať, a to ani s prístupom na zápis konceptov. Pri konverzii starých konceptov zachovajte pôvodné protokoly a na náhrady uveďte krížový odkaz. Zlyhania pri zaradení do frontu alebo nejednoznačné zlyhania doručenia vyžadujú preskúmanie, nikdy nie slepé opätovné odoslanie.

Príprava príspevkov na sociálne siete​

Podľa potreby udeľte social-channels.read, social-posts.read, social-post-drafts.read a social-post-drafts.write. members_list (members.read) dokáže vyhľadať ID používateľov hodnotiteľov. Nástroje sociálnych sietí sa zobrazujú iba vtedy, keď je udelený príslušný rozsah:

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

Prečítajte si možnosti kanála a históriu vytvorenú v Scoutello, nahrajte podklady a potom odošlite úplné varianty kanála s uvedením hodnotiteľa. Nástroje na nahrávanie vracajú pokyny HTTP PUT: preneste pôvodné bajty súboru mimo MCP a potom nahrávanie dokončite pomocou { "assetId": "..." }. Do argumentov nástrojov nevkladajte súbory kódované v base64.

Pre nové návrhy použite expectedVersion: 0 a pri čakajúcich úpravách aktuálnu verziu. mode: "validate" nevykonáva žiadne zápisy. Nástroj vráti URL na kontrolu; publikovanie alebo naplánovanie môže schváliť iba osoba používajúca dashboard. Neexistuje žiadny nástroj MCP na schválenie, publikovanie, zrušenie ani odstránenie príspevku. Nástroje pre návrhy a históriu pravidelne kontrolujte, aby ste zistili stav schválenia, dôvody zamietnutia a výsledky doručenia pre jednotlivé kanály. Skontrolované návrhy vyžadujú pre ďalšie návrhy nové externé ID.

Príklady vstupov, limity nahrávania, stránkovanie a správanie pri oneskorenom hodnotení nájdete v časti príspevky na sociálne siete na kontrolu človekom.