Preskoči na glavni sadržaj

MCP integracija

Za modularne organizacije povezana organizacija mora imati aktivan CRM modul i potrebne opsege integracije. Temeljni API vraća HTTP 403 s porukom module_not_active kada CRM pristup nije dostupan. Prije ponovnog pokušaja riješite pristup modulu u odjeljku Subscription; sama promjena API ključa neće riješiti ovu pogrešku.

Scoutello pruža udaljeni poslužitelj Model Context Protocol (MCP) za kontrolirani pristup podacima organizacije. Koristi iste integracije, API ključeve, opsege, provjere zakupca, ograničenja broja zahtjeva i ponašanje zapisa kao Scoutello REST API.

MCP koristite kada AI klijent ili agent treba otkrivati Scoutello operacije i pozivati ih kao alate. REST koristite kada aplikacija treba uobičajene HTTP krajnje točke ili generirani OpenAPI klijent. Oba sučelja koriste isti temeljni ugovor podataka.

Prije povezivanja​

Administrator organizacije mora izraditi integraciju u odjeljku Postavke organizacije → Developer/API. Prilikom izrade ili rotiranja ključa:

  1. Odaberite samo opsege za čitanje i pisanje koji su potrebni MCP klijentu.
  2. Spremite cijeli sctl_api_ ključ kada se prikaže. Scoutello ga prikazuje samo jednom.
  3. Pohranite ključ u tajnu ili konfiguraciju okruženja MCP klijenta, a ne u sustav kontrole izvornog koda.

Isti integracijski ključ može pozivati REST i MCP. Izrada zasebnog ključa samo za MCP nije potrebna niti se preporučuje. Bivši ključevi sctl_mcp_ više se ne prihvaćaju.

Vrijednosti za povezivanje​

Konfigurirajte klijent sljedećim vrijednostima:

Transport: Streamable HTTP
URL: https://admin.scoutello.com/api/v1/mcp
Header name: Authorization
Header value: Bearer YOUR_API_KEY

Zamijenite YOUR_API_KEY spremljenim integracijskim ključem. Formati konfiguracije klijenata razlikuju se, ali transport, URL i HTTP zaglavlje iznad ostaju isti. Ako klijent ne može postaviti Authorization, ključ umjesto toga može poslati u x-api-key. Nemojte konfigurirati oba zaglavlja.

Naslijeđeni URL https://admin.scoutello.com/api/mcp ostaje alias za kompatibilnost. Za nove veze koristite verzioniranu krajnju točku /api/v1/mcp.

Provjera veze​

Nakon povezivanja klijenta najprije pozovite alat whoami. Vraća trenutačnu integraciju i organizaciju, informacije o isteku i korištenju vjerodajnice, stanje ograničenja broja zahtjeva i dodijeljene opsege, bez izlaganja zapisa organizacije.

Ako whoami identificira neočekivanu organizaciju ili integraciju, odspojite klijenta i ispravite njegov ključ prije pozivanja drugog alata.

Alati i opsezi​

MCP poslužitelj oglašava samo alate dodijeljene trenutačnim ključem. Klijent ne može otkriti ni pozvati alat za pisanje koristeći samo odgovarajući opseg za čitanje.

API opsegMCP alati
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 (uključujući upsert sudionika)
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 (samo za pripremu ljudskog pregleda)
tags.readtags_list

whoami uvijek je dostupan autentificiranoj vezi. Ulazi i rezultati alata slijede iste sheme i omotače odgovora kao povezane REST operacije.

contacts_list prihvaća ograničeni search kroz imena, type, status i tagIds (polje s 1–50 ID-jeva koji odgovaraju bilo kojoj odabranoj oznaci). Svi tokeni pretraživanja moraju odgovarati polju imena; svi se filtri kombiniraju operatorom AND. Te filtre primjenjujte na svaku stranicu pokazivača. Na primjer, { "search": "Hamburg Hotel", "type": "company", "tagIds": ["tag-one", "tag-two"] } pronalazi postojeće račune koji odgovaraju kriterijima bez pretraživanja cijelog skupa.

CRM kontakti koji nisu članovi, a povezani su sa Scoutello prijavom, mogu se čitati i referencirati, dok polja članstva i računa ostaju skrivena, a uređivanje kontakata zaštićeno. Upsert samo s vanjskom poveznicom može registrirati kontakt koji se može čitati pomoću externalId, njegovog scoutelloId i neobaveznog externalUpdatedAt; izostavite sva CRM polja. Kod kasnijih ponovnih pokušaja i ažuriranja metapodataka izostavite scoutelloId. Pogledajte pravila za granice kontakata i povezivanje.

Sigurno pisanje​

Alati za skupno stvaranje ili ažuriranje mogu odmah promijeniti podatke u Scoutello. Idempotentni su za istu integraciju i vanjske ID-jeve, ali pozivatelji ipak trebaju provjeriti predviđeni resurs, organizaciju i opseg prije primjene promjena.

Postavite mode na validate kako biste pokrenuli uparivanje i provjeru bez zapisivanja. Nakon pregleda rezultata ponovite poziv s vrijednošću mode: "apply" kako biste prihvatili valjane zapise. MCP ne podržava operacije brisanja.

Pauziranje integracije odbija REST i MCP zahtjeve koji upotrebljavaju njezine ključeve. Rotiranje zamjenjuje njezinu vjerodajnicu, a opoziv trajno onemogućuje svaku vjerodajnicu koja pripada integraciji.

Otklanjanje poteškoća​

RezultatŠto provjeriti
401 pogreška autentikacijeProvjerite je li prisutan cijeli ključ i upotrebljava li zaglavlje Bearer, bez navodnika oko ključa.
403 pogreška autorizacijeDodijelite potreban opseg rotiranjem integracijskog ključa, zatim ažurirajte klijenta zamjenskim ključem.
404 na MCP URL-uProvjerite završava li URL s /api/v1/mcp. MCP usluga možda još nije omogućena u tom Scoutello okruženju.
429 pogreška ograničenja brzinePrije ponovnog pokušaja pričekajte vrijeme resetiranja navedeno u odgovoru. REST i MCP troše istu kvotu integracije.
Alat nedostajeProvjerite opsege ključa pomoću whoami; nedostupni alati namjerno se izostavljaju iz otkrivanja.

Za polja zapisa, paginaciju, ponašanje skupnih operacija i omotnice pogrešaka nastavite s referencom za Scoutello API.

Planiranje povezanih projekata​

Izradite projekt, zatim njegove prekretnice, a potom zadatke i protokole koristeći stabilne vanjske ID-jeve integracije. Novi pristup prekretnicama zahtijeva milestones.read/milestones.write; dodijelite members.read za pronalaženje članova koji se mogu dodijeliti. Postojeće se vjerodajnice ne proširuju automatski. Nakon rotiranja/dodjele pristupa osvježite otkrivanje alata i pregledajte whoami.

Za assignedContacts projekta/prekretnice upotrebljavajte Customer ID-jeve članova, a za assignedScoutelloUserIds zadatka ili ownerScoutelloUserId prilike User ID-jeve. Reference zadataka/protokola prihvaćaju projectScoutelloId ili projectExternalId, kao i odgovarajuće parove prekretnice/prilike. Veze koje sadrže samo prekretnicu određuju projekt; nepodudarnosti odbijaju stavku skupne operacije. Sudionici projekta dodaju se ili ažuriraju i izostavljeni se unosi zadržavaju.

Protokoli podržavaju bilješke projekta/prekretnice bez kontakta i status draft/final. Uvozi ovog povezanog rada nečujni su i nikad ne šalju komunikaciju. Alati za popisivanje izlažu iste filtre specifične za entitet — projekt, status, dodjelu i rok — kao REST. Prenesite potpuno iste filtre, uključujući updatedSince, kroz svaku stranicu kursora. Pogledajte referencu za API za potpuni ugovor i semantiku vrijednosti null/izostavljenih vrijednosti.

Provjerite svaku ovisnu skupnu operaciju, primijenite je, pregledajte svaki rezultat i ponovno dohvatite zapise prije nego što populaciju smatrate dovršenom. Probna izvedba ne može razriješiti nadređene zapise koji postoje samo u drugoj probnoj izvedbi. Pri ponovnom pokušaju nejasne početne veze pomoću scoutelloId najprije dohvatite zapis prema vanjskom ID-ju; bootstrap ID-jevi ne mogu se ponovno reproducirati nakon uspostave veze.

Upute za agenta za prodajne projekte​

Svaki kontakt izrađen ili ponovno upotrijebljen za prodajni projekt mora izričito upućivati na taj projekt pomoću projectScoutelloId ili projectExternalId u contacts_batch_upsert. Spominjanje projekta u bilješkama ili vanjskom ID-ju ne predstavlja članstvo. Zapisi kontakata s referencama na projekt također zahtijevaju projects.write. Ponovno dohvatite kontakt pomoću contacts.read i projects.read te provjerite projectParticipations; zadržite postojeća članstva i grupe. Generički kontakti izvan projekta ne zahtijevaju referencu na projekt.

Tvrtke i potvrđene osobe vodite kao odvojene kontakte. Povežite osobu s tvrtkom pomoću companyScoutelloId ili companyExternalId, a ne samo pomoću companyName. Promjene kontakta, odnosa s tvrtkom i članstva atomske su po stavci skupne operacije; nevažeće reference ne ostavljaju djelomično izrađen kontakt. Nemojte izmišljati osobe ni primjenjivati oznake podrijetla.

Pripremite odlazne poruke e-pošte pomoću mail_drafts_batch_upsert, nikad kao tijela protokola. Izričito dodijelite nove opsege mail-drafts.read i mail-drafts.write; priprema također zahtijeva contacts.read i projects.write. Postojeće vjerodajnice ne dobivaju nova dopuštenja automatski. Upotrijebite stabilan vanjski ID, expectedVersion: 0 za izradu, izričite reference na projekt/kontakt, User ID prihvatljivog odobravatelja i konfigurirani opseg pošiljatelja organization ili personal. Nikad nemojte nagađati adresu primatelja ni konfiguraciju pošiljatelja.

Istraživanje zadržite u content.notes; samo content.subject i content.body predstavljaju odlazni sadržaj. Izrada nacrta osigurava da je kontakt sudionik projekta. Ažuriranja moraju upotrebljavati verziju vraćenu pri posljednjem dohvaćanju; pregledani ili poslani nacrti odbijaju uređivanja. Istovjetni ponovljeni pokušaji vraćaju izvorni nacrt bez stvaranja novog pregleda. Ponovno dohvatite njegov reviewUrl, draftVersion, contentHash, status odobrenja/slanja i konačni mailScoutelloId.

Samo dodijeljena osoba može odobriti i poslati poruku putem postojećeg zaslona za pregled. Integracije ne mogu odobravati, otpremati ni slati poruke, čak ni uz pristup pisanju nacrta. Zadržite izvorne protokole pri pretvaranju starih nacrta i unakrsno navedite zamjene. Neuspjesi isporuke u redu čekanja ili nejasni neuspjesi zahtijevaju istragu, nikad slijepo ponovno slanje.

Priprema društvenih objava​

Dodijelite social-channels.read, social-posts.read, social-post-drafts.read i social-post-drafts.write prema potrebi. members_list (members.read) može pronaći ID-ove korisnika recenzenata. Društveni alati oglašavaju se samo kada im je opseg dodijeljen:

OpsegAlati
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

Pročitajte mogućnosti kanala i povijest koju je izradio Scoutello, prenesite materijale, a zatim pošaljite potpune varijante kanala s imenovanim recenzentom. Alati za prijenos vraćaju upute za HTTP PUT: izvorne bajtove datoteke prenesite izvan MCP-a, a zatim dovršite prijenos pomoću { "assetId": "..." }. Nemojte ugrađivati datoteke kodirane u base64 u argumente alata.

Upotrijebite expectedVersion: 0 za nove nacrte, a trenutačnu verziju za revizije na čekanju. mode: "validate" ne izvršava upise. Alat vraća URL za pregled; samo osoba koja upotrebljava nadzornu ploču može odobriti objavu ili zakazivanje. Ne postoji MCP alat za odobravanje, objavljivanje, otkazivanje ili brisanje objave. Alatima za nacrte i povijest provjeravajte status odobrenja, razloge odbijanja i rezultate isporuke po kanalima. Pregledani nacrti za daljnje prijedloge zahtijevaju novi vanjski ID.

Pogledajte objave na društvenim mrežama za ljudski pregled za primjere unosa, ograničenja prijenosa, straničenje i ponašanje kod zakašnjelih pregleda.