MCP-integrasjon
For modulære organisasjoner må den tilkoblede organisasjonen ha en aktiv CRM-modul samt de nødvendige omfangene for integrasjonen. Det underliggende API-et returnerer HTTP 403 med module_not_active når CRM-tilgang ikke er tilgjengelig. Løs problemet med modultilgang i Subscription før et nytt forsøk; det løser ikke feilen å endre API-nøkkelen alene.
Scoutello tilbyr en ekstern Model Context Protocol (MCP)-server for kontrollert tilgang til organisasjonsdata. Den bruker de samme integrasjonene, API-nøklene, omfangene, leietakersjekkene, hastighetsbegrensningene og postfunksjonene som Scoutello REST API.
Bruk MCP når en AI-klient eller agent skal oppdage og kalle Scoutello-operasjoner som verktøy. Bruk REST når en applikasjon trenger konvensjonelle HTTP-endepunkter eller en generert OpenAPI-klient. Begge grensesnittene bruker den samme underliggende datakontrakten.
Før tilkobling
En organisasjonsadministrator må opprette en integrasjon i Organisasjonsinnstillinger → Utvikler/API. Ved opprettelse eller rotering av nøkkelen:
- Velg bare lese- og skriveomfangene MCP-klienten trenger.
- Lagre hele
sctl_api_-nøkkelen når den vises. Scoutello viser den bare én gang. - Lagre nøkkelen i klientens hemmelighets- eller miljøkonfigurasjon, ikke i kildekodekontroll.
Den samme integrasjonsnøkkelen kan brukes til å kalle REST og MCP. Det er verken nødvendig eller anbefalt å opprette en egen MCP-nøkkel. Tidligere sctl_mcp_-nøkler godtas ikke.
Tilkoblingsverdier
Konfigurer klienten med disse verdiene:
Transport: Streamable HTTP
URL: https://admin.scoutello.com/api/v1/mcp
Header name: Authorization
Header value: Bearer YOUR_API_KEY
Erstatt YOUR_API_KEY med den lagrede integrasjonsnøkkelen. Klientenes konfigurasjonsformater varierer, men transporten, URL-en og HTTP-headeren ovenfor er de samme. Hvis en klient ikke kan angi Authorization, kan nøkkelen sendes i x-api-key i stedet. Ikke konfigurer begge headerne.
Den eldre https://admin.scoutello.com/api/mcp-URL-en er fortsatt tilgjengelig som et kompatibilitetsalias. Nye tilkoblinger bør bruke det versjonerte /api/v1/mcp-endepunktet.
Bekreft tilkoblingen
Når klienten er tilkoblet, kaller du whoami-verktøyet først. Det returnerer informasjon om gjeldende integrasjon og organisasjon, legitimasjonens utløp og bruk, status for hastighetsbegrensninger og tildelte omfang, uten å eksponere organisasjonsposter.
Hvis whoami identifiserer en uventet organisasjon eller integrasjon, kobler du fra klienten og korrigerer nøkkelen før du kaller et annet verktøy.
Verktøy og omfang
MCP-serveren annonserer bare verktøy som er tildelt den gjeldende nøkkelen. En klient kan ikke oppdage eller kalle et skriveverktøy med bare det tilsvarende leseomfanget.
| API-omfang | MCP-verktøy |
|---|---|
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 (inkludert oppretting eller oppdatering av deltakere) |
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 (bare for forberedelse til menneskelig gjennomgang) |
tags.read | tags_list |
whoami er alltid tilgjengelig for en autentisert tilkobling. Verktøyinndata og resultater følger de samme skjemaene og responskonvoluttene som de tilknyttede REST-operasjonene.
contacts_list godtar avgrensede search-søk i fornavn, etternavn og firmanavn, type, status og tagIds (en matrise med 1–50 ID-er som samsvarer med en valgt tagg). Alle søketoken må samsvare med et navnefelt; alle filtre kombineres med AND. Ta med disse filtrene på hver side med markør. { "search": "Hamburg Hotel", "type": "company", "tagIds": ["tag-one", "tag-two"] } finner for eksempel eksisterende kontoer som samsvarer, uten å skanne hele beholdningen.
Ikke-medlemskontakter i CRM som er koblet til en Scoutello-pålogging, kan leses og refereres til, mens medlemskaps- og kontofelter forblir skjult, og kontaktredigering fortsatt er beskyttet. En oppretting eller oppdatering som bare bruker en ekstern kobling, kan registrere en lesbar kontakt med externalId, den tilhørende scoutelloId og eventuelt externalUpdatedAt; utelat alle CRM-felt. Ved senere forsøk eller metadataoppdateringer utelates scoutelloId. Se grensene for kontakter og reglene for kobling.
Skriv trygt
Batch-upsert-verktøy kan endre Scoutello-data umiddelbart. De er idempotente for samme integrasjon og eksterne ID-er, men den som utfører kallet, bør likevel kontrollere ønsket ressurs, organisasjon og omfang før endringene utføres.
Sett mode til validate for å kjøre samsvarskontroll og validering uten å skrive data. Etter at resultatene er kontrollert, gjenta kallet med mode: "apply" for å godta gyldige poster. MCP tilbyr ikke slettingsoperasjoner.
Når en integrasjon settes på pause, avvises både REST- og MCP-forespørsler som bruker integrasjonens nøkler. Rotering erstatter integrasjonens legitimasjon, mens tilbakekalling deaktiverer permanent all legitimasjon som tilhører integrasjonen.
Feilsøking
| Resultat | Dette bør kontrolleres |
|---|---|
401-autentiseringsfeil | Kontroller at hele nøkkelen er med, og at toppteksten bruker Bearer, uten anførselstegn rundt nøkkelen. |
403-autorisasjonsfeil | Gi det nødvendige omfanget ved å rotere integrasjonsnøkkelen, og oppdater deretter klienten med erstatningsnøkkelen. |
404 på MCP-URL-en | Kontroller at URL-en slutter med /api/v1/mcp. MCP-tjenesten er kanskje ikke aktivert i dette Scoutello-miljøet ennå. |
429-begrensningsfeil | Vent til tidspunktet for tilbakestilling som returneres, før du prøver på nytt. REST og MCP bruker samme integrasjonskvote. |
| Verktøyet mangler | Kontroller nøkkelens omfang med whoami. Utilgjengelige verktøy utelates med hensikt fra oppdagelsen. |
For postfelter, paginering, batch-atferd og feilmeldingsstrukturer kan du se videre i Scoutello API-referansen.
Tilkoblet prosjektplanlegging
Opprett et prosjekt, deretter milepæler, og så oppgaver og protokoller ved hjelp av stabile eksterne ID-er for integrasjonen. Ny tilgang til milepæler krever milestones.read/milestones.write. Gi members.read for å slå opp medlemmer som kan tildeles. Eksisterende legitimasjon får ikke automatisk utvidede rettigheter. Etter at tilgang er rotert eller gitt, oppdater verktøyoppdagelsen og kontroller whoami.
Bruk medlemmenes Customer-ID-er for assignedContacts for prosjekt/milepæl, og User-ID-er for assignedScoutelloUserIds for oppgaver eller ownerScoutelloUserId for muligheter. Referanser til oppgaver og protokoller godtar projectScoutelloId eller projectExternalId, samt de tilsvarende milepæl-/mulighetsparene. Koblinger som bare angir en milepæl, utleder prosjektet. Avvik avvises for det aktuelle batch-elementet. Prosjektdeltakere håndteres som additive upserts, og utelatte oppføringer bevares.
Protokoller støtter kontaktløse prosjekt-/milepælsnotater og draft/final-status. Import av dette tilkoblede arbeidet skjer uten varsler og sender aldri kommunikasjon. Listeverktøyene viser de samme enhetsspesifikke filtrene for prosjekt, status, tildeling og forfallsdato som REST. Ta med de nøyaktige filtrene, inkludert updatedSince, på hver side med markør. Se API-referansen for den fullstendige kontrakten og semantikken for null og utelatte verdier.
Valider hver avhengige batch, utfør den, kontroller hvert resultat, og les postene tilbake før datamengden anses som komplett. En testkjøring kan ikke løse overordnede poster som bare finnes i en annen testkjøring. Ved nytt forsøk på en tvetydig innledende kobling med scoutelloId må det først leses etter ekstern ID. Bootstrap-ID-er kan ikke spilles av på nytt når koblingen er opprettet.
Instruksjoner for salgsprosjektagenter
Alle kontakter som opprettes eller gjenbrukes for et salgsprosjekt, må uttrykkelig referere til prosjektet ved hjelp av projectScoutelloId eller projectExternalId i contacts_batch_upsert. Det er ikke nok å nevne et prosjekt i notater eller en ekstern ID for å opprette medlemskap. Kontaktopprettinger med prosjektreferanser krever også projects.write. Les kontakten tilbake med contacts.read og projects.read, og bekreft projectParticipations. Bevar eksisterende medlemskap og grupper. Generelle kontakter utenfor et prosjekt trenger ingen prosjektreferanse.
Hold selskaper og verifiserte personer som separate kontakter. Knytt en person til selskapet med companyScoutelloId eller companyExternalId, ikke bare companyName. Endringer i kontakt, selskapsforhold og medlemskap er atomiske per batch-element. Ugyldige referanser etterlater ingen delvis opprettet kontakt. Ikke finn på personer eller legg til opprinnelsestagger.
Forbered utgående e-poster med mail_drafts_batch_upsert, aldri som protokolltekster. Gi eksplisitt de nye omfangene mail-drafts.read og mail-drafts.write. Forberedelse krever også contacts.read og projects.write. Eksisterende legitimasjon får ingen nye tillatelser automatisk. Bruk en stabil ekstern ID, expectedVersion: 0 ved opprettelse, eksplisitte prosjekt-/kontaktreferanser, User-ID-en til en godkjent godkjenner, og et konfigurert organization- eller personal-avsenderomfang. Gjett aldri mottakeradresse eller avsenderkonfigurasjon.
Hold research i content.notes. Bare content.subject og content.body er utgående tekst. Oppretting av utkast sikrer at kontakten er prosjektdeltaker. Oppdateringer må bruke versjonen fra den nyeste lesingen. Utkast som er kontrollert eller sendt, avviser redigeringer. Identiske nye forsøk returnerer det opprinnelige utkastet uten å opprette en ny kontroll. Les tilbake reviewUrl, draftVersion, contentHash, godkjennings-/sendingsstatus og den endelige mailScoutelloId.
Bare den tildelte personen kan godkjenne og sende via det eksisterende kontrollskjermbildet. Integrasjoner kan ikke godkjenne, sende videre eller sende, selv med tilgang til å skrive utkast. Bevar de opprinnelige protokollene ved konvertering av gamle utkast, og kryssreferer til erstatningene. Kølagte eller tvetydige leveringsfeil må undersøkes, aldri sendes på nytt uten kontroll.
Klargjøring av sosiale innlegg
Gi social-channels.read, social-posts.read, social-post-drafts.read og
social-post-drafts.write etter behov. members_list (members.read) kan finne
bruker-ID-er for gjennomgåere. Sosiale verktøy vises bare når det aktuelle omfanget er gitt:
| Omfang | Verktøy |
|---|---|
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 |
Les kanalfunksjoner og historikken som er opprettet av Scoutello, last opp ressurser og send deretter inn komplette kanalvarianter med en navngitt gjennomgåer. Opplastingsverktøyene returnerer HTTP PUT-instruksjoner: Overfør de opprinnelige filbytene utenfor MCP, og fullfør deretter opplastingen med { "assetId": "..." }. Ikke bygg inn base64-filer i verktøyargumenter.
Bruk expectedVersion: 0 for nye utkast og den gjeldende versjonen for ventende
revisjoner. mode: "validate" utfører ingen skriving. Verktøyet returnerer nettadressen for gjennomgang;
bare en person som bruker kontrollpanelet, kan godkjenne publisering eller planlegging. Det
finnes ikke noe MCP-verktøy for å godkjenne, publisere, avbryte eller slette et innlegg. Bruk verktøyene for
utkast og historikk til å følge med på godkjenning, avvisningsårsaker og leveringsresultater per kanal. Gjennomgåtte utkast
krever en ny ekstern ID for videre forslag.
Se sosiale innlegg til gjennomgang av personer for eksempler på inndata, opplastingsgrenser, paginering og håndtering av sen gjennomgang.