Naar hoofdinhoud gaan

MCP-integratie

Voor modulaire organisaties moet de gekoppelde organisatie beschikken over een actieve CRM-module en de vereiste scopes voor de integratie. De onderliggende API retourneert HTTP 403 met module_not_active wanneer CRM-toegang niet beschikbaar is. Los de moduletoegang op via Subscription voordat opnieuw wordt geprobeerd; alleen de API-sleutel wijzigen verhelpt deze fout niet.

Scoutello biedt een externe Model Context Protocol (MCP)-server voor gecontroleerde toegang tot organisatiegegevens. De server gebruikt dezelfde integraties, API-sleutels, scopes, tenantcontroles, snelheidslimieten en recordlogica als de Scoutello REST API.

Gebruik MCP wanneer een AI-client of agent Scoutello-bewerkingen als tools moet kunnen ontdekken en aanroepen. Gebruik REST wanneer een applicatie conventionele HTTP-eindpunten of een gegenereerde OpenAPI-client nodig heeft. Beide interfaces gebruiken hetzelfde onderliggende gegevenscontract.

Voor het verbinden​

Een organisatiebeheerder moet een integratie aanmaken via Organisatie-instellingen → Developer/API. Bij het aanmaken of roteren van de sleutel:

  1. Selecteer alleen de lees- en schrijfrechten die de MCP-client nodig heeft.
  2. Sla de volledige sctl_api_-sleutel op wanneer deze wordt weergegeven. Scoutello toont de sleutel één keer.
  3. Bewaar de sleutel in de geheimen- of omgevingsconfiguratie van de MCP-client, niet in versiebeheer.

Met dezelfde integratiesleutel kunnen REST en MCP worden aangeroepen. Een tweede, specifieke MCP-sleutel aanmaken is niet nodig en wordt niet aanbevolen. Voormalige sctl_mcp_-sleutels worden niet geaccepteerd.

Verbindingswaarden​

Configureer de client met deze waarden:

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

Vervang YOUR_API_KEY door de opgeslagen integratiesleutel. Configuratie-indelingen verschillen per client, maar het transport, de URL en de HTTP-header hierboven blijven hetzelfde. Als een client Authorization niet kan instellen, kan de sleutel in plaats daarvan worden meegestuurd in x-api-key. Configureer niet beide headers.

De oude https://admin.scoutello.com/api/mcp-URL blijft beschikbaar als compatibiliteitsalias. Nieuwe verbindingen moeten het versiegebonden /api/v1/mcp-eindpunt gebruiken.

De verbinding verifiëren​

Roep na het verbinden van de client eerst de whoami-tool aan. Deze retourneert de huidige integratie en organisatie, informatie over verloopdatum en gebruik van de inloggegevens, de status van de snelheidslimiet en de toegekende scopes, zonder organisatiegegevens bloot te geven.

Als whoami een onverwachte organisatie of integratie identificeert, verbreek dan de verbinding met de client en corrigeer de sleutel voordat een andere tool wordt aangeroepen.

Tools en scopes​

De MCP-server biedt alleen tools aan die door de huidige sleutel zijn toegekend. Een client kan een schrijftool niet ontdekken of aanroepen met alleen de bijbehorende leesscope.

API-scopeMCP-tools
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 (inclusief participant-upserts)
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 (alleen voorbereiden voor menselijke beoordeling)
tags.readtags_list

whoami is altijd beschikbaar voor een geauthenticeerde verbinding. Toolinvoer en -resultaten volgen dezelfde schema's en antwoordomhulsels als de gekoppelde REST-bewerkingen.

contacts_list accepteert begrensde search op basis van voornaam/achternaam/bedrijfsnaam, type, status en tagIds (een array met 1–50 ID's, waarbij elk geselecteerd label overeenkomt). Alle zoektokens moeten overeenkomen met een naamveld; alle filters worden gecombineerd met AND. Pas deze filters toe op elke cursorpagina. { "search": "Hamburg Hotel", "type": "company", "tagIds": ["tag-one", "tag-two"] } vindt bijvoorbeeld overeenkomende bestaande accounts zonder de volledige inventaris te doorzoeken.

CRM-contacten die geen lid zijn maar wel aan een Scoutello-login zijn gekoppeld, kunnen worden gelezen en als referentie worden gebruikt, terwijl lidmaatschaps- en accountvelden verborgen blijven en wijzigingen aan contacten afgeschermd blijven. Met een upsert die alleen een externe koppeling bevat, kan een leesbaar contact worden geregistreerd met externalId, diens scoutelloId en optioneel externalUpdatedAt; laat alle CRM-velden weg. Laat bij latere nieuwe pogingen of updates van metadata scoutelloId weg. Zie de regels voor contactgrenzen en koppelingen.

Veilig schrijven​

Batch-upserttools kunnen Scoutello-gegevens onmiddellijk wijzigen. Ze zijn idempotent voor dezelfde integratie en externe ID's, maar controleer vóór het toepassen van wijzigingen alsnog de beoogde resource, organisatie en scope.

Stel mode in op validate om matching en validatie uit te voeren zonder gegevens te schrijven. Bekijk de resultaten en herhaal de aanroep daarna met mode: "apply" om geldige records te accepteren. MCP biedt geen verwijderbewerkingen.

Een gepauzeerde integratie weigert zowel REST- als MCP-verzoeken die de bijbehorende sleutels gebruiken. Roteren vervangt de betreffende referentie, en intrekken schakelt alle referenties van de integratie permanent uit.

Problemen oplossen​

ResultaatWat moet worden gecontroleerd
401-authenticatiefoutControleer of de volledige sleutel aanwezig is en de header Bearer gebruikt, zonder aanhalingstekens rond de sleutel.
403-autorisatiefoutVerleen de vereiste scope door de integratiesleutel te roteren en werk de client vervolgens bij met de vervangende sleutel.
404 op de MCP-URLControleer of de URL eindigt op /api/v1/mcp. De MCP-service is mogelijk nog niet ingeschakeld in die Scoutello-omgeving.
429-rate-limitfoutWacht tot het opgegeven resetmoment voordat opnieuw wordt geprobeerd. REST en MCP gebruiken hetzelfde integratiequotum.
Tool ontbreektControleer de scopes van de sleutel met whoami; niet-beschikbare tools worden bewust niet in discovery opgenomen.

Ga voor recordvelden, paginering, batchgedrag en fout-enveloppen verder met de Scoutello API-referentie.

Verbonden projectplanning​

Maak eerst een project aan, daarna de mijlpalen en vervolgens de taken en protocollen, met stabiele externe ID's van de integratie. Voor toegang tot nieuwe mijlpalen zijn milestones.read/milestones.write vereist; verleen members.read om toewijsbare leden op te zoeken. Bestaande referenties krijgen niet automatisch ruimere rechten. Vernieuw na het roteren/verlenen van toegang de tool-discovery en controleer whoami.

Gebruik Customer-ID's van leden voor assignedContacts van projecten/mijlpalen, en User-ID's voor assignedScoutelloUserIds van taken of ownerScoutelloUserId van kansen. Verwijzingen naar taken/protocollen accepteren projectScoutelloId of projectExternalId, plus de overeenkomstige paren voor mijlpalen/kansen. Koppelingen die alleen naar een mijlpaal verwijzen, leiden het project af; afwijkingen wijzen het batchitem af. Projectdeelnemers worden aanvullend geüpsert; weggelaten vermeldingen blijven behouden.

Protocollen ondersteunen contactloze project-/mijlpaalnotities en de status draft/final. Imports van dit verbonden werk verlopen stil en versturen nooit communicatie. Lijsttools bieden dezelfde entiteitspecifieke filters voor projecten, status, toewijzing en vervaldatum als REST. Pas de exacte filters, inclusief updatedSince, toe op elke cursorpagina. Raadpleeg de API-referentie voor het volledige contract en de semantiek van null/weggelaten waarden.

Valideer elke afhankelijke batch, pas deze toe, controleer elk resultaat en lees de records opnieuw uit voordat de populatie als compleet wordt beschouwd. Een dry run kan geen ouders oplossen die alleen in een andere dry run bestaan. Bij het opnieuw proberen van een onduidelijke eerste koppeling met scoutelloId moet eerst op externe ID worden gelezen; bootstrap-ID's kunnen niet opnieuw worden afgespeeld zodra de koppeling bestaat.

Instructies voor sales-projectagents​

Elk contact dat voor een salesproject wordt aangemaakt of hergebruikt, moet expliciet naar dat project verwijzen met projectScoutelloId of projectExternalId in contacts_batch_upsert. Een project vermelden in notities of een externe ID vormt geen lidmaatschap. Voor contactbewerkingen met projectverwijzingen is ook projects.write vereist. Lees het contact opnieuw uit met contacts.read en projects.read en controleer projectParticipations; behoud bestaande lidmaatschappen en groepen. Voor algemene contacten buiten een project is geen projectverwijzing vereist.

Houd bedrijven en geverifieerde personen als afzonderlijke contacten. Koppel een persoon aan het bedrijf met companyScoutelloId of companyExternalId, niet alleen met companyName. Wijzigingen aan contacten, bedrijfsrelaties en lidmaatschappen zijn atomair per batchitem; ongeldige verwijzingen laten geen gedeeltelijk contact achter. Verzin geen personen en pas geen herkomsttags toe.

Bereid uitgaande e-mails voor met mail_drafts_batch_upsert, nooit als protocolteksten. Verleen de nieuwe scopes mail-drafts.read en mail-drafts.write expliciet; voor voorbereiding zijn ook contacts.read en projects.write vereist. Bestaande referenties krijgen niet automatisch nieuwe rechten. Gebruik een stabiele externe ID, expectedVersion: 0 voor het aanmaken, expliciete project-/contactverwijzingen, de User-ID van een geaccepteerde goedkeurder en een geconfigureerde organization- of personal-afzenderscope. Raad nooit een ontvangeradres of afzenderconfiguratie.

Houd onderzoek bij in content.notes; alleen content.subject en content.body zijn uitgaande copy. Bij het aanmaken van een concept wordt gewaarborgd dat het contact projectdeelnemer is. Updates moeten de versie gebruiken die bij de laatste uitlezing is teruggegeven; beoordeelde of verzonden concepten weigeren wijzigingen. Identieke nieuwe pogingen geven het oorspronkelijke concept terug zonder een nieuwe beoordeling aan te maken. Lees de reviewUrl, draftVersion, contentHash, de goedkeurings-/verzendstatus en de uiteindelijke mailScoutelloId opnieuw uit.

Alleen de toegewezen persoon kan via het bestaande beoordelingsscherm goedkeuren en verzenden. Integraties kunnen niet goedkeuren, distribueren of verzenden, zelfs niet met schrijfrechten voor concepten. Behoud oorspronkelijke protocollen bij het omzetten van oude concepten en verwijs kruisgewijs naar de vervangingen. Voor wachtrij- of onduidelijke bezorgingsfouten is onderzoek vereist; verzend nooit blind opnieuw.

Voorbereiding van socialmediaberichten​

Verleen indien nodig social-channels.read, social-posts.read, social-post-drafts.read en social-post-drafts.write. members_list (members.read) kan gebruikers-ID's van beoordelaars vinden. Sociale tools worden alleen aangeboden wanneer de bijbehorende scope is verleend:

ScopeTools
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

Lees de kanaalmogelijkheden en de door Scoutello aangemaakte geschiedenis, upload assets en dien vervolgens volledige kanaalvarianten in met een benoemde beoordelaar. Uploadtools retourneren HTTP PUT-instructies: draag de oorspronkelijke bestandsbytes buiten MCP over en voltooi de upload vervolgens met { "assetId": "..." }. Sluit geen base64-bestanden in toolargumenten in.

Gebruik expectedVersion: 0 voor nieuwe concepten en de huidige versie voor revisies die nog in behandeling zijn. mode: "validate" voert geen schrijfbewerkingen uit. De tool retourneert de beoordelings-URL; alleen een persoon die het dashboard gebruikt, kan publiceren of inplannen goedkeuren. Er is geen MCP-tool om een bericht goed te keuren, te publiceren, te annuleren of te verwijderen. Controleer concept- en geschiedenisstools op goedkeuringen, redenen voor afwijzing en leveringsresultaten per kanaal. Voor beoordeelde concepten is een nieuwe externe ID vereist voor verdere voorstellen.

Zie sociale berichten voor menselijke beoordeling voor invoervoorbeelden, uploadlimieten, paginering en informatie over te late beoordelingen.