Hoppa till huvudinnehållet

MCP-integration

För modulära organisationer måste den anslutna organisationen ha en aktiv CRM-modul samt de behörighetsomfattningar som integrationen kräver. Det underliggande API:et returnerar HTTP 403 med module_not_active när CRM-åtkomst saknas. Åtgärda modulåtkomsten i Subscription innan ett nytt försök görs; att bara byta API-nyckel löser inte felet.

Scoutello tillhandahåller en fjärrserver för Model Context Protocol (MCP) som ger kontrollerad åtkomst till organisationsdata. Den använder samma integrationer, API-nycklar, behörighetsomfattningar, hyresgästkontroller, hastighetsbegränsningar och postbeteende som Scoutello REST API.

Använd MCP när en AI-klient eller agent ska upptäcka och anropa Scoutello-operationer som verktyg. Använd REST när en applikation behöver konventionella HTTP-endpoints eller en genererad OpenAPI-klient. Båda gränssnitten använder samma underliggande datakontrakt.

Innan anslutning​

En organisationsadministratör måste skapa en integration i Organisationsinställningar → Utvecklare/API. När nyckeln skapas eller roteras:

  1. Välj endast de läs- och skrivbehörighetsomfattningar som MCP-klienten behöver.
  2. Spara hela sctl_api_-nyckeln när den visas. Scoutello visar den en gång.
  3. Lagra nyckeln i MCP-klientens hemlighets- eller miljökonfiguration, inte i källkodshanteringen.

Samma integrationsnyckel kan anropa REST och MCP. Det är varken nödvändigt eller rekommenderat att skapa en separat MCP-specifik nyckel. Tidigare sctl_mcp_-nycklar accepteras inte.

Anslutningsvärden​

Konfigurera klienten med dessa värden:

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

Ersätt YOUR_API_KEY med den sparade integrationsnyckeln. Klienternas konfigurationsformat varierar, men transporten, URL:en och HTTP-huvudet ovan är desamma. Om en klient inte kan ange Authorization kan nyckeln skickas i x-api-key i stället. Konfigurera inte båda rubrikerna.

Den äldre https://admin.scoutello.com/api/mcp-URL:en finns kvar som en kompatibilitetsalias. Nya anslutningar bör använda den versionshanterade /api/v1/mcp-endpointen.

Verifiera anslutningen​

När klienten har anslutit anropar du verktyget whoami först. Det returnerar aktuell integration och organisation, information om autentiseringsuppgifternas utgångsdatum och användning, status för hastighetsbegränsningen samt beviljade behörighetsomfattningar utan att exponera organisationsposter.

Om whoami identifierar en oväntad organisation eller integration ska klienten kopplas från och nyckeln korrigeras innan något annat verktyg anropas.

Verktyg och behörighetsomfattningar​

MCP-servern annonserar endast verktyg som den aktuella nyckeln har fått åtkomst till. En klient kan inte upptäcka eller anropa ett skrivverktyg med endast motsvarande läsbehörighet.

API-behörighetMCP-verktyg
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 deltagaruppdateringar)
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 (endast för förberedelse inför mänsklig granskning)
tags.readtags_list

whoami är alltid tillgängligt för en autentiserad anslutning. Verktygens indata och resultat följer samma scheman och svarskuvert som de länkade REST-operationerna.

contacts_list accepterar avgränsade search för förnamn, efternamn och företagsnamn, type, status samt tagIds (en array med 1–50 ID:n som matchar valfri vald tagg). Alla söklexem måste matcha ett namnfält; alla filter kombineras med AND. Behåll dessa filter på varje sida med en cursor. Exempelvis hittar { "search": "Hamburg Hotel", "type": "company", "tagIds": ["tag-one", "tag-two"] } matchande befintliga konton utan att hela lagret behöver genomsökas.

CRM-kontakter som inte är medlemmar men är länkade till en Scoutello-inloggning kan läsas och refereras, medan medlemskaps- och kontofält förblir dolda och kontaktredigeringar förblir skyddade. En upsert med endast en extern länk kan registrera en läsbar kontakt med externalId, dess scoutelloId och valfritt externalUpdatedAt; utelämna alla CRM-fält. Vid senare försök eller uppdateringar av metadata ska scoutelloId utelämnas. Se gränserna för kontakter och länkning.

Skriv säkert​

Batchupsertverktyg kan ändra Scoutello-data omedelbart. De är idempotenta för samma integration och externa ID:n, men den som anropar verktygen bör ändå granska avsedd resurs, organisation och omfattning innan ändringar tillämpas.

Ange mode till validate för att köra matchning och validering utan att skriva data. Granska resultaten och upprepa sedan anropet med mode: "apply" för att godkänna giltiga poster. MCP tillhandahåller inga borttagningsåtgärder.

När en integration pausas avvisas både REST- och MCP-anrop som använder dess nycklar. Rotation ersätter dess autentiseringsuppgift, och återkallning inaktiverar permanent alla autentiseringsuppgifter som tillhör integrationen.

Felsökning​

ResultatVad som ska kontrolleras
401-autentiseringsfelKontrollera att hela nyckeln finns med och att rubriken använder Bearer, utan citationstecken runt nyckeln.
403-behörighetsfelBevilja det obligatoriska omfånget genom att rotera integrationsnyckeln och uppdatera sedan klienten med ersättningsnyckeln.
404 på MCP-URL:enKontrollera att URL:en slutar med /api/v1/mcp. MCP-tjänsten kanske ännu inte är aktiverad i den Scoutello-miljön.
429-hastighetsbegränsningsfelVänta tills den angivna återställningstiden innan ett nytt försök görs. REST och MCP använder samma integrationskvot.
Verktyget saknasKontrollera nyckelns omfång med whoami; otillgängliga verktyg utelämnas med avsikt från upptäckten.

För postfält, paginering, batchbeteende och felsvar fortsätter du med Scoutello API-referens.

Sammanlänkad projektplanering​

Skapa först ett projekt, därefter milstolpar och sedan uppgifter och protokoll med stabila externa ID:n för integrationen. Ny åtkomst till milstolpar kräver milestones.read/milestones.write; bevilja members.read för att slå upp medlemmar som kan tilldelas. Befintliga autentiseringsuppgifter utökas inte automatiskt. Uppdatera verktygsupptäckten efter rotation eller beviljad åtkomst och granska whoami.

Använd medlemmars Customer ID:n för assignedContacts på projekt/milstolpe och User ID:n för assignedScoutelloUserIds på uppgifter eller ownerScoutelloUserId på möjligheter. Referenser till uppgifter/protokoll accepterar projectScoutelloId eller projectExternalId samt motsvarande par för milstolpe/möjlighet. Länkar som endast anger milstolpen härleder projektet; avvikelser avvisar batchobjektet. Projektdeltagare läggs till genom additiva upserts, och utelämnade poster bevaras.

Protokoll stöder kontaktlösa projekt-/milstolpeanteckningar och statusen draft/final. Import av detta sammanlänkade arbete sker tyst och skickar aldrig kommunikation. Listverktygen visar samma entitetsspecifika filter för projekt, status, tilldelning och förfallodatum som REST. För vidare exakt samma filter, inklusive updatedSince, genom varje sida med cursor. Se API-referensen för det fullständiga avtalet samt semantiken för null och utelämnade värden.

Validera varje beroende batch, tillämpa den, granska varje resultat och läs tillbaka posterna innan populationen betraktas som slutförd. En torrkörning kan inte lösa överordnade poster som endast finns i en annan torrkörning. Vid nytt försök med en tvetydig inledande länk via scoutelloId ska du först läsa med det externa ID:t; bootstrap-ID:n kan inte spelas upp igen när länken finns.

Instruktioner för säljprojektagenter​

Varje kontakt som skapas eller återanvänds för ett säljprojekt måste uttryckligen hänvisa till projektet med projectScoutelloId eller projectExternalId i contacts_batch_upsert. Att nämna ett projekt i anteckningar eller i ett externt ID innebär inte medlemskap. Kontaktändringar med projektreferenser kräver också projects.write. Läs tillbaka kontakten med contacts.read och projects.read och verifiera projectParticipations; bevara befintliga medlemskap och grupper. Generiska kontakter utanför ett projekt behöver ingen projektreferens.

Håll företag och verifierade personer som separata kontakter. Länka en person till företaget med companyScoutelloId eller companyExternalId, inte enbart med companyName. Ändringar av kontakt, företagsrelation och medlemskap är atomära per batchobjekt; ogiltiga referenser lämnar ingen delvis skapad kontakt. Hitta inte på personer och lägg inte till ursprungstaggar.

Förbered utgående e-post med mail_drafts_batch_upsert, aldrig som protokolltext. Bevilja uttryckligen de nya omfången mail-drafts.read och mail-drafts.write; förberedelse kräver också contacts.read och projects.write. Befintliga autentiseringsuppgifter får inga nya behörigheter automatiskt. Använd ett stabilt externt ID, expectedVersion: 0 för skapande, explicita projekt-/kontaktreferenser, User ID:t för en godkänd granskare samt ett konfigurerat avsändaromfång för organization eller personal. Gissa aldrig mottagaradress eller avsändarkonfiguration.

Håll research i content.notes; endast content.subject och content.body är utgående text. När ett utkast skapas säkerställs att kontakten är projektdeltagare. Uppdateringar måste använda den version som returnerades vid den senaste läsningen; granskade eller skickade utkast avvisar ändringar. Identiska nya försök returnerar det ursprungliga utkastet utan att skapa ytterligare en granskning. Läs tillbaka dess reviewUrl, draftVersion, contentHash, godkännande-/sändningsstatus och slutliga mailScoutelloId.

Endast den tilldelade personen kan godkänna och skicka via den befintliga granskningsvyn. Integrationer kan inte godkänna, skicka vidare eller sända, inte ens med åtkomst för att skriva utkast. Bevara ursprungliga protokoll när gamla utkast konverteras och korsreferera ersättningarna. Köade eller tvetydiga leveransfel kräver utredning, aldrig en blind omsändning.

Förberedelse av sociala inlägg​

Bevilja social-channels.read, social-posts.read, social-post-drafts.read och social-post-drafts.write vid behov. members_list (members.read) kan hitta användar-ID:n för granskare. Sociala verktyg visas endast när deras behörighet har beviljats:

BehörighetVerktyg
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 kanalernas funktioner och historik som skapats av Scoutello, ladda upp resurser och skicka sedan in fullständiga kanalvarianter med en namngiven granskare. Uppladdningsverktyg returnerar instruktioner för HTTP PUT: överför originalfilens bytevärden utanför MCP och slutför sedan uppladdningen med { "assetId": "..." }. Bädda inte in base64-filer i verktygsargument.

Använd expectedVersion: 0 för nya utkast och den aktuella versionen för väntande revideringar. mode: "validate" utför inga skrivåtgärder. Verktyget returnerar gransknings-URL:en; endast en person som använder instrumentpanelen kan godkänna publicering eller schemaläggning. Det finns inget MCP-verktyg för att godkänna, publicera, avbryta eller radera ett inlägg. Kontrollera utkast-/historikverktygen för godkännande, orsaker till avslag och leveransresultat per kanal. Granskade utkast kräver ett nytt externt ID för ytterligare förslag.

Se sociala inlägg för mänsklig granskning för indataexempel, uppladdningsbegränsningar, paginering och information om försenad granskning.