Hop til hovedindhold

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:

  1. Vælg kun de læse- og skrivescopes, som MCP-klienten har brug for.
  2. Gem hele sctl_api_-nøglen, når den vises. Scoutello viser den én gang.
  3. 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-scopeMCP-værktøjer
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 (inklusive oprettelse eller opdatering af deltagere)
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 (kun til forberedelse af menneskelig gennemgang)
tags.readtags_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​

ResultatHvad skal kontrolleres
401-godkendelsesfejlKontrollér, at hele nøglen er med, og at headeren bruger Bearer, uden anførselstegn omkring nøglen.
403-adgangsfejlTildel det påkrævede omfang ved at rotere integrationsnøglen, og opdatér derefter klienten med den nye nøgle.
404 på MCP-URL'enKontrollé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ænseVent, indtil det returnerede nulstillingstidspunkt, før der prøves igen. REST og MCP bruger den samme integrationskvote.
Værktøjet manglerKontrollé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:

ScopeVærktøjer
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

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.