MCP-integration
For modulære organisationer skal den tilknyttede organisation have et aktivt CRM-modul samt de scopes, integrationen kræver. Den underliggende API returnerer HTTP 403 med module_not_active, når CRM-adgang ikke er tilgængelig. Aktivér moduladgangen under Subscription, før forsøget gentages. Det løser ikke fejlen alene at ændre API-nøglen.
Scoutello leverer en ekstern Model Context Protocol (MCP)-server til kontrolleret adgang til organisationsdata. Den bruger de samme integrationer, API-nøgler, scopes, lejerkontroller, hastighedsbegrænsninger og postfunktioner som Scoutello REST API.
Brug MCP, når en AI-klient eller -agent skal kunne finde og kalde Scoutello-handlinger som værktøjer. Brug REST, når en applikation har brug for almindelige HTTP-endpoints eller en genereret OpenAPI-klient. Begge grænseflader bruger den samme underliggende datakontrakt.
Før forbindelsen oprettes
En organisationsadministrator skal oprette en integration under Organisationsindstillinger → Developer/API. Når nøglen oprettes eller roteres:
- Vælg kun de læse- og skrivescopes, som MCP-klienten har brug for.
- Gem hele
sctl_api_-nøglen, når den vises. Scoutello viser den én gang. - Gem nøglen i MCP-klientens hemmeligheds- eller miljøkonfiguration, ikke i kildekontrollen.
Den samme integrationsnøgle kan kalde REST og MCP. Det er hverken nødvendigt eller anbefalet at oprette en særskilt MCP-nøgle. Tidligere sctl_mcp_-nøgler accepteres ikke.
Forbindelsesværdier
Konfigurér klienten med disse værdier:
Transport: Streamable HTTP
URL: https://admin.scoutello.com/api/v1/mcp
Header name: Authorization
Header value: Bearer YOUR_API_KEY
Erstat YOUR_API_KEY med den gemte integrationsnøgle. Klienternes konfigurationsformater varierer, men transporten, URL'en og HTTP-headeren ovenfor er de samme. Hvis en klient ikke kan angive Authorization, kan den i stedet sende nøglen i x-api-key. Konfigurér ikke begge headere.
Den ældre https://admin.scoutello.com/api/mcp-URL forbliver et kompatibilitetsalias. Nye forbindelser bør bruge det versionsstyrede /api/v1/mcp-endpoint.
Kontrollér forbindelsen
Når klienten har oprettet forbindelse, skal værktøjet whoami kaldes først. Det returnerer oplysninger om den aktuelle integration og organisation, legitimationsoplysningernes udløb og brug, status for hastighedsbegrænsningen samt tildelte scopes uden at eksponere organisationsposter.
Hvis whoami identificerer en uventet organisation eller integration, skal klienten afbrydes, og nøglen skal rettes, før et andet værktøj kaldes.
Værktøjer og scopes
MCP-serveren annoncerer kun de værktøjer, som den aktuelle nøgle har fået tildelt. En klient kan ikke finde eller kalde et skriveværktøj med kun det tilsvarende læsescope.
| API-scope | MCP-værktøjer |
|---|---|
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 (inklusive oprettelse eller opdatering af deltagere) |
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 (kun til forberedelse af menneskelig gennemgang) |
tags.read | tags_list |
whoami er altid tilgængelig for en godkendt forbindelse. Værktøjsinput og -resultater følger de samme skemaer og svarindpakninger som de tilknyttede REST-handlinger.
contacts_list accepterer afgrænsede search-værdier på tværs af fornavn/efternavn/virksomhedsnavn, type, status og tagIds (et array med 1–50 ID'er, der matcher et vilkårligt valgt tag). Alle søgetokens skal matche et navnefelt; alle filtre kombineres med AND. Filtrene skal medtages på hver side med en cursor. { "search": "Hamburg Hotel", "type": "company", "tagIds": ["tag-one", "tag-two"] } finder for eksempel matchende eksisterende konti uden at gennemgå hele beholdningen.
CRM-kontakter, der ikke er medlemmer, men som er knyttet til et Scoutello-login, kan læses og refereres, mens medlemskabs- og kontofelter forbliver skjulte, og kontaktændringer fortsat er beskyttede. En oprettelse eller opdatering, der kun bruger en ekstern reference, kan registrere en læsbar kontakt ved hjælp af externalId, kontaktens scoutelloId og eventuelt externalUpdatedAt. Udelad alle CRM-felter. Ved senere forsøg eller metadataopdateringer skal scoutelloId udelades. Se reglerne for kontaktgrænser og sammenkædning.
Sikker skrivning
Batch-upsert-værktøjer kan ændre Scoutello-data med det samme. De er idempotente for den samme integration og de samme eksterne ID'er, men kaldere bør stadig kontrollere den tiltænkte ressource, organisation og det tiltænkte omfang, før ændringer anvendes.
Indstil mode til validate for at køre matchning og validering uden at skrive. Når resultaterne er gennemgået, gentages kaldet med mode: "apply" for at acceptere gyldige poster. MCP eksponerer ikke slettehandlinger.
Midlertidig deaktivering af en integration afviser både REST- og MCP-anmodninger, der bruger dens nøgler. Rotation erstatter dens legitimationsoplysninger, og tilbagekaldelse deaktiverer permanent alle legitimationsoplysninger, der tilhører integrationen.
Fejlfinding
| Resultat | Hvad skal kontrolleres |
|---|---|
401-godkendelsesfejl | Kontrollér, at hele nøglen er med, og at headeren bruger Bearer, uden anførselstegn omkring nøglen. |
403-adgangsfejl | Tildel det påkrævede omfang ved at rotere integrationsnøglen, og opdatér derefter klienten med den nye nøgle. |
404 på MCP-URL'en | Kontrollér, at URL'en slutter med /api/v1/mcp. MCP-tjenesten er muligvis endnu ikke aktiveret i det pågældende Scoutello-miljø. |
429-fejl på grund af hastighedsgrænse | Vent, indtil det returnerede nulstillingstidspunkt, før der prøves igen. REST og MCP bruger den samme integrationskvote. |
| Værktøjet mangler | Kontrollér nøglens omfang med whoami; utilgængelige værktøjer udelades med vilje fra opdagelsen. |
Se videre i Scoutello API-reference for postfelter, paginering, batchadfærd og fejlsvar.
Forbundet projektplanlægning
Opret et projekt, derefter dets milepæle og til sidst opgaver og protokoller ved hjælp af stabile eksterne ID'er for integrationen. Adgang til nye milepæle kræver milestones.read/milestones.write; tildel members.read for at slå medlemmer op, der kan tildeles. Eksisterende legitimationsoplysninger udvides ikke automatisk. Når adgangen er roteret eller tildelt, skal værktøjsopdagelsen opdateres, og whoami skal gennemgås.
Brug medlemmers Customer ID'er til assignedContacts for projekt/milepæl, og User ID'er til assignedScoutelloUserIds for opgaver eller ownerScoutelloUserId for muligheder. Referencer til opgaver/protokoller accepterer projectScoutelloId eller projectExternalId samt de tilsvarende milepæls-/mulighedspar. Links, der kun angiver en milepæl, udleder projektet; uoverensstemmelser afviser batchelementet. Projektdeltagere opdateres kumulativt og bevarer udeladte poster.
Protokoller understøtter kontaktløse projekt-/milepælsnoter og statusserne draft/final. Import af dette forbundne arbejde er lydløs og sender aldrig kommunikation. Listeværktøjer viser de samme enhedsspecifikke filtre for projekt, status, tildeling og forfaldsdato som REST. De nøjagtige filtre, herunder updatedSince, skal medtages på hver side med en markør. Se API-referencen for den komplette kontrakt samt semantikken for null og udeladte værdier.
Validér hver afhængige batch, anvend den, gennemgå hvert resultat, og læs posterne tilbage, før populationen betragtes som fuldført. En prøvekørsel kan ikke løse overordnede poster, der kun findes i en anden prøvekørsel. Ved gentagelse af et tvetydigt indledende link med scoutelloId skal der først læses efter eksternt ID; bootstrap-ID'er kan ikke afspilles igen, når linket findes.
Instruktioner til salgsprojektagenter
Alle kontakter, der oprettes eller genbruges til et salgsprojekt, skal udtrykkeligt referere til projektet ved hjælp af projectScoutelloId eller projectExternalId i contacts_batch_upsert. Det er ikke et medlemskab blot at nævne et projekt i noter eller et eksternt ID. Kontaktskrivninger med projektreferencer kræver også projects.write. Læs kontakten tilbage med contacts.read og projects.read, og kontrollér projectParticipations; eksisterende medlemskaber og grupper skal bevares. Generiske kontakter uden for et projekt kræver ikke en projektreference.
Hold virksomheder og verificerede personer som separate kontakter. Knyt en person til virksomheden med companyScoutelloId eller companyExternalId, ikke kun med companyName. Ændringer af kontakt, virksomhedsrelation og medlemskab er atomiske pr. batchelement; ugyldige referencer efterlader ingen delvis kontakt. Opfind ikke personer, og anvend ikke oprindelsesmærker.
Forbered udgående e-mails med mail_drafts_batch_upsert, aldrig som protokoltekster. Tildel eksplicit de nye omfang mail-drafts.read og mail-drafts.write; forberedelse kræver også contacts.read og projects.write. Eksisterende legitimationsoplysninger får ikke automatisk nye tilladelser. Brug et stabilt eksternt ID, expectedVersion: 0 ved oprettelse, eksplicitte projekt-/kontaktreferencer, en godkendende persons User ID samt et konfigureret afsenderomfang for organization eller personal. Gæt aldrig en modtageradresse eller afsenderkonfiguration.
Opbevar research i content.notes; kun content.subject og content.body er udgående tekst. Oprettelse af et udkast sikrer, at kontakten er projektdeltager. Opdateringer skal bruge den version, der blev returneret ved den seneste læsning; gennemgåede eller afsendte udkast afviser redigeringer. Identiske gentagelser returnerer det oprindelige udkast uden at oprette endnu en gennemgang. Læs reviewUrl, draftVersion, contentHash, godkendelses-/afsendelsesstatus og den endelige mailScoutelloId tilbage.
Kun den tildelte person kan godkende og sende via den eksisterende gennemgangsskærm. Integrationer kan ikke godkende, ekspedere eller sende, heller ikke med adgang til at skrive udkast. Bevar de oprindelige protokoller, når gamle udkast konverteres, og krydshenvis til erstatningerne. Køede eller tvetydige leveringsfejl kræver undersøgelse, aldrig en blind genafsendelse.
Forberedelse af opslag på sociale medier
Tildel social-channels.read, social-posts.read, social-post-drafts.read og
social-post-drafts.write efter behov. members_list (members.read) kan finde
bruger-ID'er for anmeldere. Sociale værktøjer vises kun, når deres scope er tildelt:
| Scope | Værktøjer |
|---|---|
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 |
Læs kanalernes funktioner og historik oprettet af Scoutello, upload aktiver, og indsend derefter
komplette kanalvarianter med en navngiven anmelder. Uploadværktøjer returnerer HTTP PUT
-instruktioner: Overfør de oprindelige filbytes uden for MCP, og færdiggør derefter
uploaden med { "assetId": "..." }. Indlejring af base64-filer i værktøjsargumenter er ikke tilladt.
Brug expectedVersion: 0 til nye kladder og den aktuelle version til afventende
revisioner. mode: "validate" foretager ingen skrivninger. Værktøjet returnerer URL'en til gennemgangen;
kun en person, der bruger dashboardet, kan godkende publicering eller planlægning. Der findes
ikke noget MCP-værktøj til at godkende, publicere, annullere eller slette et opslag. Afstem kladde- og historikværktøjerne
for godkendelser, begrundelser for afvisning og leveringsresultater pr. kanal. Gennemgåede kladder
kræver et nyt eksternt ID til yderligere forslag.
Se sociale opslag til manuel gennemgang for eksempler på input, uploadgrænser, sideinddeling og håndtering af sene gennemgange.