MCP

Customermates exponiert einen MCP-Endpoint unter https://customermates.com/api/v1/mcp. Ein verbundener Client entdeckt automatisch alle 48 CRM-Tools. Es gibt zwei Wege zu verbinden:

• Custom Connector (OAuth): für Claude (Web, Desktop, Mobile) und ChatGPT. URL einfügen, anmelden, freigeben. Kein Key zu verwalten. Starten Sie auf Mit einem Custom Connector verbinden.
• API-Key: für CLI- und Editor-Clients (Claude Code, Codex, Cursor, Gemini CLI) und rohe HTTP-Aufrufe. Den 64-Zeichen-Key im Header x-api-key oder einer Konfigurationsdatei senden.

Für das End-to-End-Setup auf einer Seite springen Sie zu Ihrem Client: Claude Desktop, ChatGPT, Claude Code, Codex, Cursor oder Gemini. Diese Seite ist die Protokoll-Referenz.

Wann MCP passt

• Ihre KI soll das CRM lesen und schreiben, ohne dass Sie IDs kopieren.
• Die KI soll Fähigkeiten entdecken, statt dass Sie API-Calls von Hand schreiben.
• Ein Endpoint für Claude, ChatGPT, Cursor, Codex und weitere Clients.

Nehmen Sie stattdessen OpenAPI, wenn ein Entwickler oder Integrations-Service genau weiß, welchen Endpoint er braucht. OpenAPI ist die kanonische HTTP-Referenz. MCP ist die Agent-native Oberfläche darüber.

Der Endpoint

POST https://customermates.com/api/v1/mcp
Content-Type: application/json
Accept: application/json, text/event-stream
x-api-key: <ihr-64-zeichen-key>

Der Endpoint spricht Model Context Protocol (Streamable-HTTP-Variante). tools/list liefert jedes Tool mit JSON Schema. tools/call ruft ein Tool per Name auf.

Da es die Streamable-HTTP-Variante ist, muss jede Anfrage Accept: application/json, text/event-stream senden. Ohne diesen Header liefert der Endpoint 406 Not Acceptable. Die dokumentierten Client-Anleitungen konfigurieren den unterstützten Verbindungsweg; rohe HTTP-Aufrufe mit curl oder Skripten müssen den Header explizit ergänzen.

Der x-api-key-Header ist die API-Key-Methode. Der Key ist 64 Zeichen lang, base62 (a-z, A-Z, 0-9), und erbt die Rechte des Users, der ihn erstellt hat. Es gibt kein Scoping pro Key. Custom-Connector-Clients (Claude, ChatGPT) authentifizieren sich stattdessen per OAuth und senden ein Bearer-Token, das sie für Sie holen und erneuern. Siehe Mit einem Custom Connector verbinden.

Client verbinden

Einen AI-Client mit dem Workspace zu verbinden sind immer dieselben drei Schritte:

1. API-Key erstellen

   Profil → API Keys → Neuer Key. Entweder das geführte Setup für Claude, ChatGPT, Cursor oder Gemini wählen, oder einen Standard-Key für die eigene Integration. Der Key wird nur einmal angezeigt, also vor dem Schließen des Dialogs kopieren.

2. Client auf den Endpoint zeigen lassen

   Dem Client POST https://customermates.com/api/v1/mcp mit dem x-api-key-Header aus dem vorherigen Schritt geben, oder per OAuth verbinden, wo der Client das unterstützt. Die Guides pro Client in der Tabelle unten enthalten die genaue Konfiguration.

3. Prüfen, ob die Tools ankommen

   Den Client nach seinen Tools fragen. Alle 48 sollten erscheinen, und get_workspace_context ist der natürliche erste Aufruf: er liefert User, Company, Rollen und verbundene Accounts auf einmal.

Der Server stellt beim Verbinden Anweisungen bereit. Ob ein Client sie an das Modell übergibt und wie das Modell ihnen folgt, hängt vom konkreten Client ab. Clients mit MCP-Prompt-Unterstützung können zusätzlich den eingebauten get-started-Prompt für einen personalisierten Start ausführen.

Server-Instructions, Prompts und Toolsets

Der Server sendet beim Verbinden Hinweise zum Ablauf: zuerst das Schema lesen, IDs vor dem Schreiben suchen, Beziehungen nur über manage_record_links ändern und vor Löschen oder Senden nachfragen. Diese Hinweise bilden keine serverseitig erzwungene Freigabe. Prüfen Sie, wie der gewählte Client die Anweisungen an das Modell weitergibt und Bestätigungen behandelt, bevor Sie Schreib-, Lösch- oder Messaging-Zugriff gewähren. In Clients mit MCP-Prompt-Unterstützung kann ein eingebauter Get-Started-Prompt den Workspace für den Einstieg zusammenfassen.

Die volle 48-Tool-Oberfläche ist der Standard. Hängen Sie ?toolsets= an die Endpoint-URL, um sie einzugrenzen, zum Beispiel /api/v1/mcp?toolsets=records,messaging. Keys und Details stehen unter Eingrenzen mit ?toolsets=.

Wie die Tool-Oberfläche gebaut ist

Die MCP-Oberfläche ist so gebaut, dass auch Modelle mit schwächerer Planung sie zuverlässig nutzen können:

• Verb-first-imperative Namen: create_contacts, update_deals, delete_records. Kein Batch-Präfix. Das Verb passt zur Absicht.
• Zusammengeführte Peripherie: Custom Columns, Widgets und Webhooks liegen jeweils hinter einem Tool (manage_custom_columns, manage_widgets, manage_webhooks) mit action-Schalter, sodass das Modell eine Action wählt statt zwischen vielen fast identischen Tools.
• Inline-Enum-Hinweise: jedes Enum-Feld listet gültige Werte inline in der Beschreibung, sodass das Modell keine externen Typen auflösen muss.
• Filter-Beispiele inline: jeder filters-Parameter hat ein konkretes JSON-Beispiel in der Beschreibung.
• Relationship-Sicherheit: Beziehungen ändern sich nur über manage_record_links (add oder remove); null auf einem Relationship-Array wird mit Remediation-Hint abgelehnt.
• Unveränderlicher Spaltentyp: manage_custom_columns hält type und entityType beim Update fest (aus der bestehenden Spalte übernommen); ein Typwechsel bedeutet löschen und neu anlegen.
• Destructive-Flags: jedes destruktive Tool und jede destruktive Action hat destructiveHint: true und beginnt mit IRREVERSIBLE.

CLI-Nutzung

Wenn Sie einen lokalen Client statt GUI wollen, verbinden Tools wie mcporter denselben Endpoint. API-Key einmal in der Client-Config speichern und Tools aus der Shell aufrufen.

OpenAPI neben MCP

Beide liegen an derselben Basis-URL. MCP nutzt /api/v1/mcp, die OpenAPI-Spezifikation /api/v1/openapi. Die OpenAPI-Operationen entsprechen den REST-Endpunkten. MCP bildet unterstützte Operationen als typisierte Tools mit Anweisungen, Metadaten und derselben Produkt-Autorisierung ab. Die Anweisungen fügen keine zweite serverseitige Bestätigung hinzu.

Tool-Katalog

Customermates exponiert 48 MCP-Tools, alle standardmäßig aktiviert. Sie decken Records, Workspace, Messaging, Social Posts, Dokumentation und Deep Research, Custom Columns, Widgets, Webhooks, Admin und Support ab. Jedes destruktive Tool ist geflaggt und startet die Beschreibung mit IRREVERSIBLE. Beziehungen ändern sich nur über manage_record_links; die Update-Tools fassen sie nie an.

Zwei Flags pro Tool:

• Read: keine Mutation.
• Destructive: löscht Daten oder ist nicht rückgängig zu machen. Bei zusammengeführten Tools gilt das Flag für die löschenden Actions.

Das volle JSON-Schema jedes Tools liegt live an POST /api/v1/mcp mit method: "tools/list".

Records

Siebzehn Tools arbeiten gegen die fünf Record-Typen (contact, organization, deal, service, task). Records tragen pro Workspace definierte Custom Columns, deshalb ist get_record_schema der Anker: Es liefert die Custom-Column-IDs und Optionswerte, die Schreibzugriffe brauchen. Felder wie ein Deal- oder Task-Status sind konfigurierbare singleSelect Custom Columns, keine festen nativen Felder; get_record_schema liefert genau die Spalten, die der Workspace tatsächlich hat.

Alle Create- und Update-Tools nehmen Custom-Column-Werte über customFieldValues; rufen Sie zuerst get_record_schema für die Column-IDs auf.

Workspace

Messaging

Messaging-basierte Tools sind im Cloud-Modus ab dem Pro-Tarif verfügbar. get_activities kann ohne Messaging-Berechtigung weiterhin Änderungen aus dem Audit-Log liefern, wenn der aufrufende User die Audit-Log-Berechtigung hat. Nachrichten, Aktivitäten verbundener Accounts und Kalenderquellen erfordern zusätzlich die Berechtigung für den Posteingang und Messaging.

Social Posts

Typischer Social-Read-Ablauf

Wählen Sie aus get_workspace_context.connectedAccounts einen LinkedIn- oder Instagram-Eintrag mit status=ok und verwenden Sie dessen id als connectedAccountId. Wenn die Person aus einem Inbox-Thread stammt, lösen Sie zuerst get_messaging_threads.items[].participants[].identifier aus dem Listenmodus oder get_messaging_threads.thread.participants[].identifier aus dem Detailmodus auf:

{
  "connectedAccountId": "00000000-0000-4000-8000-000000000001",
  "identifier": "<get_messaging_threads.items[].participants[].identifier>",
  "profileType": "person"
}

Rufen Sie get_social_profile mit dieser Anfrage auf und übergeben Sie anschließend get_social_profile.id als get_social_posts.authorIdentifier für die erste Seite:

{
  "connectedAccountId": "00000000-0000-4000-8000-000000000001",
  "authorIdentifier": "<get_social_profile.id>",
  "limit": 10
}

Wenn next_cursor nicht null ist, wiederholen Sie dieselben Werte für connectedAccountId, authorIdentifier und limit, setzen Sie cursor auf diesen Wert und lassen Sie offset weg:

{
  "connectedAccountId": "00000000-0000-4000-8000-000000000001",
  "authorIdentifier": "<same get_social_profile.id>",
  "cursor": "<next_cursor>",
  "limit": 10
}

Für ein Unternehmen rufen Sie get_social_profile mit profileType=company und einem identifier aus linkedin_search_sales_companies.items[].id, linkedin_search_sales_leads.items[].current_positions[].company_id, linkedin_manage_sales_lists.items[].current_positions[].company_id oder get_social_profile.current_positions[].company_id auf.

Dokumentation und Deep Research

Custom Columns

Widgets

Routinen

Webhooks

Admin und Team

Support

Eingrenzen mit ?toolsets=

Alle 48 Tools sind standardmäßig an. Um nur einen Teil der Oberfläche zu exponieren, hängen Sie ?toolsets= mit kommagetrennten Gruppen-Keys an die Endpoint-URL:

https://customermates.com/api/v1/mcp?toolsets=records,messaging

Keys: records, workspace, messaging, social, docs, custom-columns, widgets, routines, webhooks, admin, support. Kein Parameter heißt alles; unbekannte Keys werden ignoriert. search und fetch sind immer an, damit Deep-Research-Connectors auch auf einer eingegrenzten Oberfläche funktionieren.

Wenn ein Aufruf abgelehnt wird

Eine Ablehnung ist Datum, kein Absturz. Das Ergebnis trägt isError: true, eine menschenlesbare Nachricht in content und einen maschinenlesbaren Umschlag in _meta.failure mit kind und den betroffenen issues, die jeweils den Feld-path benennen:

{
  "isError": true,
  "content": [{ "type": "text", "text": "Webhook ID not found or not accessible." }],
  "_meta": {
    "failure": {
      "kind": "not_found",
      "issues": [{ "code": "custom", "path": [], "message": "Webhook ID not found or not accessible.", "customCode": "webhookNotFound" }]
    }
  }
}

kind ist eines von validation, authentication, authorization, not_found, conflict, rate_limit oder unavailable. Darauf verzweigen statt Nachrichtentexte zu matchen:

• validation: die Argumente waren falsch. issues[].path lesen, das Feld korrigieren, erneut aufrufen. get_record_schema klärt die meisten dieser Fälle.
• authorization: die Rolle des Aufrufers erlaubt es nicht. Wiederholen hilft nie; benennen, was abgelehnt wurde und welche Berechtigung es braucht. Rollen sind workspace-definiert, also get_workspace_context.roles lesen statt einen festen Satz anzunehmen.
• not_found: die Id existiert nicht oder gehört zu einem anderen Workspace. Jeder Aufruf ist mandantengebunden, eine fremde Id liest sich daher als fehlend, nicht als verboten.
• conflict: etwas belegt die Ressource bereits. Vor dem Wiederholen den aktuellen Stand lesen.
• rate_limit und unavailable: vorübergehend oder kapazitätsbedingt. Zurückhalten, und unavailable als Provider-Problem darstellen, nicht als Fehler des Users.
• authentication: der Key fehlt, ist abgelaufen oder widerrufen. Der User muss einen neuen ausstellen.

Entitlements lehnen auf demselben Weg ab. Messaging-gestützte Tools brauchen die Pro-Stufe, Sales-Navigator-Tools das entsprechende LinkedIn-Abo, und das Verbinden eines Accounts endet am Kanal-Limit des Plans. Berechtigung und Entitlement sind unabhängig: ein Aufrufer kann Inbox-Berechtigung haben und trotzdem am Plan scheitern, und umgekehrt.

Tool-Metadaten und serverseitige Grenzen

• Bestätigungshinweis für den Client. Die Server-Anweisungen fordern das Modell auf, vor delete_records und jedem Versand-Tool nachzufragen. Der MCP-Endpunkt führt einen autorisierten Tool-Aufruf aus, sobald der Client ihn sendet. Prüfen Sie daher das Bestätigungsverhalten des Clients.
• Beziehungen nur über manage_record_links. Die Update-Tools fassen Beziehungen nie an, und null auf einem Relationship-Array wird serverseitig mit Remediation-Hint abgelehnt.
• Erst Draft, dann Send. send_email und send_chat_message stellen sofort zu. Wer eine Nachricht vorbereitet haben will, bekommt sie über save_message_draft, und Sie senden sie aus der Inbox. Ein Draft braucht keine bestehende Unterhaltung: Mit connectedAccountId und recipients entsteht der Thread lokal, erscheint in der Inbox und erreicht den Anbieter erst beim Senden.
• Destructive-Flags überall. Jedes destruktive Tool und jede destruktive Action hat destructiveHint: true und den Präfix IRREVERSIBLE in der Beschreibung.
• Jedes Enum-Feld listet gültige Werte inline in der Beschreibung, und jedes filters-Feld enthält ein konkretes JSON-Beispiel.

Häufige Fragen

Weiter

• Custom Connector: End-to-End-Setup auf einer Seite.
• Filter-Syntax: jeder Operator mit Beispielen.
• Webhooks: die andere Hälfte des agentischen Loops.