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:
- Nur die Lese- und Schreibberechtigungen auswählen, die der MCP-Client benötigt.
- Den vollständigen
sctl_api_-Schlüssel speichern, sobald er angezeigt wird. Scoutello zeigt ihn nur einmal an. - 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-Berechtigungsbereich | MCP-Tools |
|---|---|
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 (einschließlich Upserts von Teilnehmenden) |
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 (nur zur Vorbereitung der manuellen Prüfung) |
tags.read | tags_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
| Ergebnis | Zu prüfen |
|---|---|
401-Authentifizierungsfehler | Prüfen, ob der vollständige Schlüssel vorhanden ist und der Header Bearer verwendet, ohne Anführungszeichen um den Schlüssel. |
403-Autorisierungsfehler | Den erforderlichen Geltungsbereich durch Rotation des Integrationsschlüssels gewähren und anschließend den Client mit dem Ersatzschlüssel aktualisieren. |
404 an der MCP-URL | Prüfen, ob die URL mit /api/v1/mcp endet. Der MCP-Dienst ist in dieser Scoutello-Umgebung möglicherweise noch nicht aktiviert. |
429-Ratenlimitfehler | Vor einem erneuten Versuch bis zur zurückgegebenen Zurücksetzungszeit warten. REST und MCP verwenden dasselbe Integrationskontingent. |
| Tool fehlt | Die 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:
| Scope | Tools |
|---|---|
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 |
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.