SMOC mit MCP zu Claude oder einem anderen KI-basierten Client verbinden

Einfache Anleitung, wie Sie SMOC mit KI-Clients und Entwicklungstools über MCP (Model Context Protocol) verbinden. Nach der Verbindung können Tools wie Claude Desktop, Claude Code, Cursor oder VS Code Ihre SMOC-Daten direkt lesen – Kontakte, Unternehmen, Unternehmensressourcen, Flussdiagramme, Flow-Analysen, LinkedIn-Postfäden und Nachrichtenablauf-Konversationen – jeweils auf Ihr Unternehmen beschränkt. HTTP-Clients sollten die REST v2 API-Referenz verwenden.

API-Schlüssel erhalten

Die SMOC MCP-Integration authentifiziert sich mit einem privaten API-Schlüssel. Erstellen Sie einen Schlüssel in der SMOC Console:

1. Gehen Sie zu Einstellungen → Integrationen → MCP.
2. Geben Sie optional einen Namen und ein Ablaufdatum (7, 30 oder 90 Tage) an. Lassen Sie das Ablaufdatum auf Kein Ablauf, wenn Sie kein Ablaufdatum wünschen.
3. Erstellen Sie den Schlüssel und kopieren Sie ihn sofort – er wird nur einmal angezeigt, also speichern Sie ihn sicher.

Ihr Schlüssel ist an Ihr Unternehmen gebunden. Jede Anfrage damit ist automatisch auf Ihre Daten beschränkt – Sie sehen nur Kontakte, Unternehmen, Analysen, Postfäden und Konversationen, die zu Ihnen gehören. Das Erstellen eines neuen Schlüssels widerruft nicht bestehende Schlüssel. Ausgestellte Schlüssel werden auf derselben Seite aufgelistet – widerrufen Sie dort nicht verwendete Schlüssel.

Die API- und Zapier-Seiten verwenden denselben Namen, Ablauf, Kopierhinweis und die Liste ausgestellter Schlüssel.

Auf was Sie zugreifen können

Nach der Verbindung stehen folgende Tools zur Verfügung (die genaue Verfügbarkeit hängt von den Berechtigungen Ihres Kontos und den konfigurierten Serverbindungen ab). Schlüssel sind standardmäßig nur lesend. Aktivieren Sie Begrenzte Schreibrechte erlauben beim Erstellen eines Schlüssels, um die unten aufgeführten Schreibvorgänge zu ermöglichen.

Discovery

• whoami — aktuelle Rolle, Unternehmensbereich und Berechtigungen
• mcp_capabilities — sichtbare Tools, Fähigkeiten und aktuell nicht verfügbare Elemente
• skills_search — ein Rezept anhand einer kurzen Aufgabenbeschreibung finden
• skills_get — genaue Eingaben und ein Beispiel für eine Fähigkeit

Unternehmen & Ressourcen

• companies_get — Unternehmensprofil (Titel, Schlüssel, URL, Sprachen, Einstellungen)
• company_assets_get — Produkte, Positionierung, Webseiten-Links und Dateien
• company_asset_extraction_results_list — Zusammenfassungen von Extraktionsergebnissen
• company_asset_extraction_results_get — ein Extraktionsergebnis, optional mit extrahierten Daten
• company_asset_extraction_templates_list — Vorlagen, Tags und Aktualität

Super-User-Schlüssel können außerdem companies_list aufrufen, um alle Unternehmen zu durchsuchen, bevor ein companyId ausgewählt wird.

Kontakte

• contacts_search — Suche mit Filtern, Sortierung und Paginierung
• contacts_get — ein bereinigter Kontakt nach ID
• contacts_get_stats — Zählungen und Engagement-Zusammenfassung
• contacts_get_filter_options — gültige Filterwerte (Standort, Ablauf, Gerät und Ähnliches)
• contact_tags_list — Kontakt-Tags
• prospect_lists_list / prospect_lists_get — Interessentenlisten

Postfach & Konversationen

• inbox_threads_list — LinkedIn- (und andere) Postfäden, mit ungelesen / unbeantwortet / Absender / Ablauf-Filtern
• inbox_threads_get — ein Thread; setzen Sie includeMessages: true, um aktuelle Nachrichten einzuschließen
• inbox_messages_list — Nachrichtenverlauf für einen Thread, einschließlich zusammengeführter Peer-Threads
• conversations_list — Nachrichtenablauf-Durchläufe (Anmeldung, Status, aktueller Knoten)
• conversations_get — ein Konversationsdurchlauf, einschließlich Meilensteinen

Postfach-Tools benötigen die Berechtigung inbox:read. Sie können Nachrichteninhalte lesen. Schreibberechtigte Schlüssel können außerdem archivieren, als ungelesen/erledigt markieren und eine nur-Text-Antwort mit inbox_threads_send senden (erfordert threadId, body und idempotencyKey). Sie können keine Dateien anhängen, Ablaufdiagramme bearbeiten, Abläufe veröffentlichen oder LinkedIn-Outreach-Kampagnen starten. Super-User-Schlüssel können Mongo-Ablauf- und Themenentwürfe speichern (flowcharts_save, flowcharts_create, themes_save und verwandte Aufrufe), einschließlich Web-/Nachrichten- und Chat-/Karten-Typen. Diese Schreibvorgänge veröffentlichen nicht.

Flussdiagramme

• flowcharts_list — statische Flussdiagramme für das Unternehmen
• flowcharts_get — eine Flussdiagramm-Zusammenfassung oder vollständiger Graph
• flowchart_recommendations_list — Empfehlungsschreiben für ein Flussdiagramm
• flowcharts_versions_list, themes_get, studio_generation_categories_list, Targeting-Portfolios sowie Lesezugriffe auf Generierungs-/Übersetzungsjobs
• Super-User-Entwurfs-Schreibvorgänge: flowcharts_save, flowcharts_restore_version, flowcharts_create (flowType Web oder Nachricht, webFormat Chat oder Karte), flowcharts_duplicate, themes_save. Diese schreiben Mongo-Entwürfe und veröffentlichen nicht.
• CPCS-Lesezugriffe: cpcs_overview, URLs, Crawls, Extraktionen, Vorlagen, Zeitpläne

Flow-Analysen

• analytics_flow_list_flows — Abläufe nach Traffic sortiert
• analytics_flow_kpis — Gesamtzahlen, Conversion, Veränderungen zum Vorzeitraum
• analytics_flow_timeseries — Tages- oder Monatstrends
• analytics_flow_dimension_metrics — Aufschlüsselungen nach Gerät, Land, Sprache, UTM oder Wochentag
• analytics_flow_filter_values — gültige Analyse-Filterwerte

Kundenschlüssel sind immer auf das eigene Unternehmen beschränkt. Super-User-Schlüssel können companyId auf eingeschränkten Tools verwenden.

---

Verbindung in Claude (Web und Desktop)

Fügen Sie SMOC als benutzerdefinierten Connector hinzu. Das funktioniert auf claude.ai und in der Claude Desktop-App. Sie können sich mit Ihrem SMOC-Konto anmelden oder mit einem API-Schlüssel verbinden.

Schnellstart

MCP-Endpunkt: https://api.smoc.ai/mcp

Anmelden

1. Öffnen Sie in Claude Anpassen, dann + Hinzufügen.
2. Benennen Sie den Connector SMOC und fügen Sie den MCP-Endpunkt ein. Anmeldung aktiviert lassen. Wählen Sie nicht Keine Anmeldung und fügen Sie keinen Anfrage-Header hinzu.
3. Wenn Claude Sie auffordert, sich zu verbinden, melden Sie sich mit einem Unternehmens-Admin-Konto an.
4. Öffnen Sie in einem Chat +, wählen Sie Connectors und aktivieren Sie SMOC. Bitten Sie Claude, whoami auszuführen.

Die Anmeldung ist nur für Unternehmens-Admins. Sie kann die Daten dieses Unternehmens lesen. Mitglieder und andere Rollen sind ausgeschlossen. Sie ermöglicht nicht die begrenzten Schreibrechte, die Sie beim Erstellen eines API-Schlüssels aktivieren. Wenn Sie mehr als ein Unternehmen verwalten, verwenden Sie einen API-Schlüssel für das gewünschte Unternehmen.

Bei Team und Enterprise fügt ein Owner den Connector unter Organisationseinstellungen → Connectors → + Hinzufügen → Benutzerdefiniert hinzu. Mitglieder aktivieren ihn dann unter Anpassen.

Oder API-Schlüssel hinzufügen

1. Erstellen Sie einen API-Schlüssel unter Einstellungen → Integrationen → MCP und kopieren Sie ihn.
2. Öffnen Sie in Claude Anpassen, dann + Hinzufügen.
3. Benennen Sie den Connector SMOC und fügen Sie den MCP-Endpunkt ein.
4. Wählen Sie Keine Anmeldung. Unter Request headers wählen Sie authorization und setzen den Wert auf Bearer YOUR_SMOC_API_KEY – das Wort Bearer und das Leerzeichen einschließen. Markieren Sie den Header als erforderlich und fügen Sie dann den Connector hinzu.

Verwenden Sie einen Schlüssel, wenn Sie ein bestimmtes Unternehmen, ein Ablaufdatum oder begrenzte Schreibrechte wünschen. Anfrage-Header werden schrittweise eingeführt. Falls + Hinzufügen keinen Bereich für Request headers hat, verwenden Sie Claude Code oder die Desktop-Konfigurationsdatei unten.

Verbindung in ChatGPT

ChatGPT fügt SMOC als App hinzu. Der Erstellungsbildschirm verwendet Anmeldung und hat kein Feld für einen API-Schlüssel. Melden Sie sich mit einem Unternehmens-Admin-Konto an.

Schnellstart

MCP-Endpunkt: https://api.smoc.ai/mcp

1. Öffnen Sie Einstellungen → Apps → Erweiterte Einstellungen und aktivieren Sie Entwicklermodus. Bei Business, Enterprise oder Edu aktiviert ein Workspace-Admin dies zuerst unter Workspace-Einstellungen → Berechtigungen & Rollen.
2. Öffnen Sie Apps → Erstellen. Benennen Sie die App SMOC und fügen Sie den MCP-Endpunkt ein.
3. Wählen Sie OAuth, dann Tools scannen. Melden Sie sich mit einem Unternehmens-Admin-Konto an, wenn ChatGPT dazu auffordert, und klicken Sie dann auf Erstellen.
4. Öffnen Sie im Chat das Tools-Menü und aktivieren Sie SMOC. Bitten Sie ChatGPT, whoami auszuführen.

Die Anmeldung ist nur für Unternehmens-Admins. Sie kann die Daten dieses Unternehmens lesen. Mitglieder sind ausgeschlossen. API-Schlüssel sind für Claude, Cursor und VS Code. ChatGPT benötigt einen Plus-, Pro-, Business-, Enterprise- oder Edu-Plan für benutzerdefinierte Apps.

Verbindung zu Claude Desktop mit einer Konfigurationsdatei

Verwenden Sie dies, wenn der Connector-Dialog keinen API-Schlüssel akzeptiert. SMOC verbindet sich dann über eine kleine lokale Bridge (mcp-remote).

1. Öffnen Sie Claude Desktop → Einstellungen → Entwickler → Konfiguration bearbeiten. Dies öffnet claude_desktop_config.json.
2. Fügen Sie SMOC unter mcpServers hinzu:

{
  "mcpServers": {
    "smoc": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.smoc.ai/mcp",
        "--header",
        "Authorization: Bearer YOUR_SMOC_API_KEY"
      ]
    }
  }
}

3. Ersetzen Sie YOUR_SMOC_API_KEY durch den von Ihnen generierten Schlüssel.
4. Speichern Sie die Datei und starten Sie Claude Desktop neu.

SMOC erscheint nun in Ihrer Tool-Liste. Erfordert installiertes Node.js (für npx).

---

Verbindung zu Claude Code

Claude Code kann direkt mit dem SMOC-Endpunkt über einen Authentifizierungs-Header kommunizieren – keine Bridge nötig.

claude mcp add --transport http smoc https://api.smoc.ai/mcp \
  --header "Authorization: Bearer YOUR_SMOC_API_KEY"

Ab Claude Code 2.1.1 und neuer können Sie es auch als JSON hinzufügen:

claude mcp add-json smoc \
  '{"type":"http","url":"https://api.smoc.ai/mcp","headers":{"Authorization":"Bearer YOUR_SMOC_API_KEY"}}'

Überprüfen Sie die Verbindung, indem Sie /mcp in einer Claude Code-Sitzung ausführen – SMOC sollte als verbunden mit aufgelisteten Tools angezeigt werden.

---

Verbindung zu anderen Clients (Cursor, VS Code, Windsurf usw.)

Die meisten MCP-fähigen Editoren verwenden eine JSON-Konfigurationsdatei (oft mcp.json). Fügen Sie einen HTTP-Server-Eintrag hinzu, der auf den SMOC-Endpunkt zeigt, mit Ihrem Schlüssel im Authorization-Header:

{
  "mcpServers": {
    "smoc": {
      "type": "http",
      "url": "https://api.smoc.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_SMOC_API_KEY"
      }
    }
  }
}

Sehen Sie in der MCP-Dokumentation Ihres Editors nach, wo sich die Datei genau befindet. Nach dem Speichern starten Sie den Editor neu oder laden ihn neu.

---

Verbindung überprüfen

• Health Check: Der Endpunkt stellt GET https://api.smoc.ai/mcp/health bereit.
• Identitätsprüfung: Bitten Sie die KI, das Tool whoami auszuführen – es gibt zurück, als wen Sie verbunden sind und welchen Unternehmensbereich Sie haben. Das ist der schnellste Weg, um zu bestätigen, dass der Schlüssel funktioniert.

Tools entdecken

Die KI muss die Namen der SMOC-Tools nicht im Voraus kennen. Der vorgesehene Ablauf ist:

1. mcp_capabilities — listet die verfügbaren Tools, Ihre Rolle und Ihren Bereich auf.
2. skills_search — beschreiben Sie die Aufgabe in einem kurzen Satz, um das richtige Tool zu finden.
3. skills_get — gibt die genauen Eingaben und ein Beispiel für das gewählte Tool zurück.
4. Tool aufrufen.

In der Praxis können Sie einfach in natürlicher Sprache fragen (z. B. "suche meine SMOC-Kontakte in Oslo" oder "zeige unbeantwortete LinkedIn-Postfäden") und der Client wählt das richtige Tool aus.

Sicherheitshinweise

• Ihr API-Schlüssel wird nur einmal bei der Erstellung angezeigt – speichern Sie ihn in einem Passwort-Manager oder einer Umgebungsvariable.
• Geben Sie den Schlüssel niemals in ein Git-Repository ein oder fügen Sie ihn in eine gemeinsam genutzte/öffentliche Konfiguration ein.
• Das Erstellen eines neuen Schlüssels widerruft nicht bestehende Schlüssel. Widerrufen Sie nicht verwendete Schlüssel in der Liste ausgestellter Schlüssel unter Einstellungen → Integrationen → MCP.
• Kundenschlüssel sind standardmäßig nur lesend und auf Ihre Unternehmensdaten beschränkt. Schreibberechtigte Schlüssel können Kontakte, Tags, Listen, Unternehmensprofil aktualisieren, CPCS-URLs hinzufügen, Postfach triagieren und Textantworten im Postfach senden. Sie können keine Daten löschen, Abläufe veröffentlichen, Live umschalten oder LinkedIn-Outreach-Kampagnen starten.
• Postfach- und Konversationstools benötigen inbox:read auf dem Schlüssel. Neue Schlüssel aus Einstellungen → Integrationen → MCP enthalten dies; ältere Schlüssel benötigen eine Rotation.

Fehlerbehebung

• Tools fehlen in der Liste: Die KI kann mcp_capabilities ausführen und unavailableTools prüfen – dort steht die genau fehlende Berechtigung, die Ihr Schlüssel benötigt.
• Authentifizierung schlägt fehl: Überprüfen Sie, ob der Schlüssel korrekt ist, nicht widerrufen wurde und der Header exakt Authorization: Bearer <key> ist.
• Claude's + Hinzufügen-Dialog hat keinen Bereich für Request headers: Verwenden Sie den Claude Code-Befehl oder die oben genannte mcp-remote-Konfiguration. Stellen Sie sicher, dass Node.js installiert ist, das Konfigurations-JSON gültig ist und Sie Claude Desktop nach der Bearbeitung der Konfiguration vollständig neu gestartet haben.

Siehe auch

• REST v2 API-Referenz – jeder POST /api/v2/{toolName}-Aufruf
• SMOC mit der REST API verbinden
• Öffentliche Kontakte-API
• MCP für Claude, Cursor und VS Code