Zum Hauptinhalt springen

MCP-Integration

Bei modularen Organisationen benötigt die verbundene Organisation ein aktives CRM-Modul sowie die für die Integration erforderlichen Berechtigungsbereiche. Die zugrunde liegende API gibt module_not_active mit HTTP-Status 403 zurück, wenn der CRM-Zugriff nicht verfügbar ist. Den Modulzugriff unter Subscription aktivieren, bevor ein weiterer Versuch gestartet wird. Das Ändern des API-Schlüssels allein behebt diesen Fehler nicht.

Scoutello stellt einen entfernten Model Context Protocol (MCP)-Server für den kontrollierten Zugriff auf Organisationsdaten bereit. Dabei gelten dieselben Integrationen, API-Schlüssel, Berechtigungsbereiche, Mandantenprüfungen, Ratenbegrenzungen und Datensatzregeln wie bei der Scoutello REST API.

MCP eignet sich, wenn ein KI-Client oder -Agent Scoutello-Operationen als Tools erkennen und aufrufen soll. REST eignet sich, wenn eine Anwendung herkömmliche HTTP-Endpunkte oder einen generierten OpenAPI-Client benötigt. Beide Schnittstellen verwenden denselben zugrunde liegenden Datenvertrag.

Vor der Verbindung​

Eine Organisationsadministration muss unter Organisationseinstellungen → Developer/API eine Integration erstellen. Beim Erstellen oder Rotieren des Schlüssels:

  1. Nur die Lese- und Schreibberechtigungen auswählen, die der MCP-Client benötigt.
  2. Den vollständigen sctl_api_-Schlüssel speichern, sobald er angezeigt wird. Scoutello zeigt ihn nur einmal an.
  3. Den Schlüssel in den Geheimnis- oder Umgebungsvariablen des MCP-Clients speichern, nicht in der Versionsverwaltung.

Mit demselben Integrationsschlüssel können REST und MCP aufgerufen werden. Das Erstellen eines zweiten, MCP-spezifischen Schlüssels ist weder erforderlich noch empfohlen. Frühere sctl_mcp_-Schlüssel werden nicht akzeptiert.

Verbindungswerte​

Den Client mit diesen Werten konfigurieren:

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

YOUR_API_KEY durch den gespeicherten Integrationsschlüssel ersetzen. Die Konfigurationsformate unterscheiden sich je nach Client, Transport, URL und HTTP-Header bleiben jedoch wie oben angegeben. Wenn ein Client Authorization nicht setzen kann, kann der Schlüssel stattdessen in x-api-key übertragen werden. Nicht beide Header konfigurieren.

Die bisherige https://admin.scoutello.com/api/mcp-URL bleibt als Kompatibilitätsalias bestehen. Für neue Verbindungen sollte der versionierte /api/v1/mcp-Endpunkt verwendet werden.

Verbindung überprüfen​

Nach dem Verbindungsaufbau des Clients zuerst das Tool whoami aufrufen. Es gibt Informationen zur aktuellen Integration und Organisation, zum Ablauf und zur Nutzung der Zugangsdaten, zum Status der Ratenbegrenzung sowie zu den erteilten Berechtigungsbereichen zurück, ohne Organisationsdatensätze offenzulegen.

Wenn whoami eine unerwartete Organisation oder Integration ausweist, die Verbindung trennen und den Schlüssel korrigieren, bevor ein weiteres Tool aufgerufen wird.

Tools und Berechtigungsbereiche​

Der MCP-Server stellt nur Tools bereit, die durch den aktuellen Schlüssel autorisiert sind. Ein Client kann ein Schreibtool nicht ausschließlich mit dem entsprechenden Leseberechtigungsbereich erkennen oder aufrufen.

API-BerechtigungsbereichMCP-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 (einschließlich Upserts von Teilnehmenden)
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 (nur zur Vorbereitung der manuellen Prüfung)
tags.readtags_list

whoami ist für eine authentifizierte Verbindung immer verfügbar. Eingaben und Ergebnisse der Tools folgen denselben Schemata und Antwortstrukturen wie die zugehörigen REST-Operationen.

contacts_list akzeptiert begrenzte search für Vor-, Nach- und Unternehmensnamen, type, status und tagIds (ein Array mit 1–50 IDs, die einem ausgewählten Tag entsprechen). Alle Suchbegriffe müssen mit einem Namensfeld übereinstimmen; alle Filter werden mit AND verknüpft. Diese Filter auf jeder Cursor-Seite übernehmen. So findet { "search": "Hamburg Hotel", "type": "company", "tagIds": ["tag-one", "tag-two"] } beispielsweise passende vorhandene Konten, ohne den gesamten Bestand zu durchsuchen.

Nichtmitglieder unter den CRM-Kontakten, die mit einem Scoutello-Login verknüpft sind, können gelesen und referenziert werden. Mitgliedschafts- und Kontofelder bleiben jedoch verborgen, und Kontaktänderungen bleiben geschützt. Ein Upsert ausschließlich über eine externe Verknüpfung kann einen lesbaren Kontakt mit externalId, dessen scoutelloId und optionalem externalUpdatedAt registrieren; alle CRM-Felder weglassen. Bei späteren Wiederholungsversuchen oder Metadatenaktualisierungen wird scoutelloId weggelassen. Weitere Informationen enthält die Abgrenzung und Regeln für Verknüpfungen von Kontakten.

Sicher schreiben​

Batch-Upsert-Tools können Scoutello-Daten unmittelbar ändern. Für dieselbe Integration und dieselben externen IDs sind sie idempotent. Vor dem Anwenden von Änderungen sollte jedoch weiterhin die vorgesehene Ressource, Organisation und der Geltungsbereich geprüft werden.

mode auf validate setzen, um Abgleich und Validierung ohne Schreibvorgang auszuführen. Anschließend die Ergebnisse prüfen und den Aufruf mit mode: "apply" wiederholen, um gültige Datensätze zu übernehmen. MCP stellt keine Löschvorgänge bereit.

Das Pausieren einer Integration weist sowohl REST- als auch MCP-Anfragen zurück, die ihre Schlüssel verwenden. Durch die Rotation wird ihr Zugangsschlüssel ersetzt. Durch den Widerruf werden alle Zugangsdaten der Integration dauerhaft deaktiviert.

Fehlerbehebung​

ErgebnisZu prüfen
401-AuthentifizierungsfehlerPrüfen, ob der vollständige Schlüssel vorhanden ist und der Header Bearer verwendet, ohne Anführungszeichen um den Schlüssel.
403-AutorisierungsfehlerDen erforderlichen Geltungsbereich durch Rotation des Integrationsschlüssels gewähren und anschließend den Client mit dem Ersatzschlüssel aktualisieren.
404 an der MCP-URLPrüfen, ob die URL mit /api/v1/mcp endet. Der MCP-Dienst ist in dieser Scoutello-Umgebung möglicherweise noch nicht aktiviert.
429-RatenlimitfehlerVor einem erneuten Versuch bis zur zurückgegebenen Zurücksetzungszeit warten. REST und MCP verwenden dasselbe Integrationskontingent.
Tool fehltDie Geltungsbereiche des Schlüssels mit whoami prüfen. Nicht verfügbare Tools werden bei der Discovery absichtlich ausgelassen.

Weitere Informationen zu Datensatzfeldern, Seitennavigation, Batch-Verhalten und Fehlerumschlägen enthält die Scoutello API-Referenz.

Verbundene Projektplanung​

Ein Projekt erstellen, anschließend Meilensteine und danach Aufgaben und Protokolle mit stabilen externen IDs der Integration anlegen. Für den Zugriff auf neue Meilensteine ist milestones.read/milestones.write erforderlich. Zum Nachschlagen zuweisbarer Mitglieder members.read gewähren. Vorhandene Zugangsdaten erhalten nicht automatisch erweiterte Berechtigungen. Nach Rotation oder Gewährung des Zugriffs die Tool-Discovery aktualisieren und whoami prüfen.

Für assignedContacts von Projekten und Meilensteinen die Customer IDs der Mitglieder verwenden, für assignedScoutelloUserIds von Aufgaben und ownerScoutelloUserId von Verkaufschancen die User IDs. Verweise auf Aufgaben und Protokolle akzeptieren projectScoutelloId oder projectExternalId sowie die entsprechenden Meilenstein-/Verkaufschancen-Paare. Links, die nur auf einen Meilenstein verweisen, leiten das Projekt ab. Abweichungen führen zur Ablehnung des Batch-Elements. Projektteilnehmende werden additiv per Upsert verarbeitet; ausgelassene Einträge bleiben erhalten.

Protokolle unterstützen kontaktlose Projekt-/Meilensteinnotizen sowie den Status draft/final. Importe dieser verbundenen Arbeit erfolgen ohne Benachrichtigungen und lösen niemals Kommunikation aus. Listen-Tools stellen dieselben entitätsspezifischen Projekt-, Status-, Zuweisungs- und Fälligkeitsfilter wie REST bereit. Alle exakten Filter, einschließlich updatedSince, durch jede Cursor-Seite weitergeben. Der vollständige Vertrag sowie die Semantik von Nullwerten und ausgelassenen Feldern sind in der API-Referenz beschrieben.

Jeden abhängigen Batch validieren, anwenden, jedes Ergebnis prüfen und die Datensätze erneut abrufen, bevor die Befüllung als abgeschlossen gilt. Ein Testlauf kann übergeordnete Datensätze, die nur in einem anderen Testlauf existieren, nicht auflösen. Beim erneuten Versuch einer nicht eindeutig bestimmten anfänglichen Verknüpfung mit scoutelloId zuerst nach der externen ID suchen. Bootstrap-IDs können nicht erneut verwendet werden, sobald die Verknüpfung besteht.

Anweisungen für Vertriebsprojekt-Agenten​

Jeder Kontakt, der für ein Vertriebsprojekt erstellt oder wiederverwendet wird, muss dieses Projekt in contacts_batch_upsert ausdrücklich über projectScoutelloId oder projectExternalId referenzieren. Die Erwähnung eines Projekts in Notizen oder einer externen ID stellt keine Mitgliedschaft dar. Kontakt-Schreibvorgänge mit Projektverweisen erfordern außerdem projects.write. Den Kontakt mit contacts.read und projects.read erneut abrufen und projectParticipations prüfen. Bestehende Mitgliedschaften und Gruppen beibehalten. Allgemeine Kontakte außerhalb eines Projekts benötigen keinen Projektverweis.

Unternehmen und verifizierte Personen als separate Kontakte führen. Eine Person mit dem Unternehmen über companyScoutelloId oder companyExternalId verknüpfen, nicht ausschließlich über companyName. Änderungen an Kontakt, Unternehmensbeziehung und Mitgliedschaft sind pro Batch-Element atomar. Ungültige Verweise hinterlassen keinen teilweise erstellten Kontakt. Keine Personen erfinden und keine Herkunftstags anwenden.

Ausgehende E-Mails mit mail_drafts_batch_upsert vorbereiten, niemals als Protokolltext. Die neuen Geltungsbereiche mail-drafts.read und mail-drafts.write ausdrücklich gewähren. Für die Vorbereitung sind außerdem contacts.read und projects.write erforderlich. Vorhandene Zugangsdaten erhalten nicht automatisch neue Berechtigungen. Eine stabile externe ID, expectedVersion: 0 für die Erstellung, explizite Projekt-/Kontaktverweise, die User ID einer genehmigenden Person sowie einen konfigurierten Versand-Geltungsbereich organization oder personal verwenden. Niemals eine Empfängeradresse oder Absenderkonfiguration erraten.

Recherche in content.notes belassen; nur content.subject und content.body sind ausgehender Text. Durch die Erstellung eines Entwurfs wird sichergestellt, dass der Kontakt Projektteilnehmende:r ist. Aktualisierungen müssen die bei der letzten Abfrage zurückgegebene Version verwenden. Bereits geprüfte oder versendete Entwürfe weisen Bearbeitungen zurück. Identische Wiederholungen geben den ursprünglichen Entwurf zurück, ohne eine weitere Prüfung zu erstellen. reviewUrl, draftVersion, contentHash, den Genehmigungs-/Versandstatus und den späteren mailScoutelloId erneut abrufen.

Nur die zugewiesene Person kann über die vorhandene Prüfungsansicht genehmigen und senden. Integrationen können auch mit Zugriff zum Schreiben von Entwürfen weder genehmigen noch zustellen oder senden. Beim Umwandeln älterer Entwürfe die ursprünglichen Protokolle beibehalten und die Ersatzversionen gegenseitig referenzieren. Warteschlangen- oder nicht eindeutig bestimmte Zustellfehler untersuchen, niemals blind erneut senden.

Vorbereitung von Social-Media-Beiträgen​

social-channels.read, social-posts.read, social-post-drafts.read und social-post-drafts.write je nach Bedarf gewähren. Mit members_list (members.read) die User-IDs der prüfenden Personen ermitteln. Social-Tools werden nur angezeigt, wenn ihr jeweiliger Scope erteilt wurde:

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

Die Kanal-Funktionen und den von Scoutello erstellten Verlauf lesen, Assets hochladen und anschließend vollständige Kanalvarianten mit einer benannten prüfenden Person übermitteln. Upload-Tools geben Anweisungen für HTTP PUT zurück: Die ursprünglichen Dateibytes außerhalb von MCP übertragen und den Upload anschließend mit { "assetId": "..." } abschließen. Keine Base64-Dateien in Tool-Argumente einbetten.

expectedVersion: 0 für neue Entwürfe und die aktuelle Version für ausstehende Überarbeitungen verwenden. mode: "validate" führt keine Schreibvorgänge aus. Das Tool gibt die URL für die Prüfung zurück; nur eine Person, die das Dashboard verwendet, kann die Veröffentlichung oder Planung genehmigen. Es gibt kein MCP-Tool zum Genehmigen, Veröffentlichen, Abbrechen oder Löschen eines Beitrags. Entwurfs- und Verlaufs-Tools regelmäßig nach Genehmigungen, Ablehnungsgründen und kanalbezogenen Zustellergebnissen abfragen. Geprüfte Entwürfe benötigen für weitere Vorschläge eine neue externe ID.

Weitere Informationen zu Eingabebeispielen, Upload-Limits, Seitennummerierung und dem Verhalten bei verspäteten Prüfungen stehen unter Social-Posts zur manuellen Prüfung.