Erste Schritte
KI verbinden
Integrationen
Self-Hosting
Customermates exponiert einen nativen MCP-Endpoint unter /api/v1/mcp, damit Claude, ChatGPT, Cursor und andere Agent-Clients das CRM direkt lesen und schreiben können.
Customermates exponiert einen MCP-Endpoint unter https://customermates.com/api/v1/mcp. Ein verbundener Client entdeckt automatisch alle 46 CRM-Tools. Es gibt zwei Wege zu verbinden:
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.
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.
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 Request Accept: application/json, text/event-stream senden. Ohne diesen Header liefert der Endpoint 406 Not Acceptable. Alle unterstützten MCP-Clients setzen ihn automatisch; nur rohe HTTP-Aufrufe (curl, Skripte) müssen ihn 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 | Methode | Guide |
|---|---|---|
| Claude Web & Mobile | Custom Connector (OAuth) | Mit einem Custom Connector verbinden |
| Claude Desktop | Connector (OAuth) oder Config-Key | Claude Desktop verbinden |
| ChatGPT | Connector (OAuth) oder Key-Header | ChatGPT verbinden |
| Claude Code | API-Key | Claude Code verbinden |
| Codex | API-Key | Codex verbinden |
| Cursor | API-Key | Cursor verbinden |
| Gemini CLI | API-Key | Gemini verbinden |
| Beliebiger MCP-Client | Key-Header | Endpoint und Header oben nutzen |
Der Server brieft das Modell automatisch, sobald sich ein Client verbindet. Clients, die MCP-Prompts unterstützen, können zusätzlich den eingebauten get-started-Prompt für einen personalisierten Start ausführen.
Sie müssen dem Modell nicht beibringen, wie es das CRM nutzt. Der Server sendet beim Verbinden Instructions, sodass das Modell den Workflow automatisch befolgt: erst das Schema lesen, IDs vor dem Schreiben suchen, Beziehungen nur über manage_record_links ändern und vor Löschen oder Senden rückfragen. In Clients, die MCP-Prompts unterstützen (Claude Code, Cursor), gibt es zusätzlich einen eingebauten Get-Started-Prompt; er interviewt Sie kurz und fasst Ihren Workspace zusammen, um den Start zu personalisieren.
Die volle 46-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=.
Die MCP-Oberfläche ist so gebaut, dass auch Modelle mit schwächerer Planung sie zuverlässig nutzen können:
create_contacts, update_deals, delete_records. Kein Batch-Präfix. Das Verb passt zur Absicht.manage_custom_columns, manage_widgets, manage_webhooks) mit action-Schalter, sodass das Modell eine Action wählt statt zwischen vielen fast identischen Tools.filters-Parameter hat ein konkretes JSON-Beispiel in der Beschreibung.manage_record_links (add oder remove); null auf einem Relationship-Array wird mit Remediation-Hint abgelehnt.manage_custom_columns hält type und entityType beim Update fest (aus der bestehenden Spalte übernommen); ein Typwechsel bedeutet löschen und neu anlegen.destructiveHint: true und beginnt mit IRREVERSIBLE.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.
Beide liegen an derselben Base-URL. MCP auf /api/v1/mcp; die OpenAPI-Spec auf /api/v1/openapi. Die OpenAPI-Operationen mappen 1:1 auf REST-Endpoints; MCP-Tools wrappen diese und ergänzen Safety-Guardrails, die die Raw-API nicht hat.
Customermates exponiert 46 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:
Das volle JSON-Schema jedes Tools liegt live an POST /api/v1/mcp mit method: "tools/list".
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.
| Tool | Read | Destructive | Zweck |
|---|---|---|---|
get_record_schema | ✓ | Schema und Custom-Column-Metadaten, nie Record-Daten. Ein Entity-Typ, oder alle fünf, wenn entity fehlt. Vor jedem Create oder Update aufrufen. | |
list_records | ✓ | Suchen, filtern, sortieren, paginieren für einen Entity-Typ. Liefert immer das Total. Deals enthalten totalValue und totalQuantity, Services amount. | |
search_records | ✓ | Freitextsuche über einen oder mehrere Entity-Typen in einem Call. | |
get_records | ✓ | Volle Record-Daten per ID, bis 100, Typen mischbar; Contacts auch per E-Mail, Telefon oder provider:handle. Liefert immer die Felder; Markdown-Notes je Eintrag mit include=withNotes. | |
create_contacts | Bis 100 Contacts anlegen, Custom-Column-Werte und Relations-IDs inline. | ||
create_organizations | Bis 100 Organizations anlegen, Custom-Column-Werte und Contact-/User-/Deal-/Task-IDs inline. | ||
create_deals | Bis 100 Deals anlegen, Services als Inline-Array. | ||
create_services | Bis 100 Services anlegen, Custom-Column-Werte und User-/Deal-/Task-IDs inline. | ||
create_tasks | Bis 100 Tasks anlegen, Custom-Column-Werte und Relations-IDs inline. | ||
update_contacts | Partial-Update per Contact-Key (ID, E-Mail, Telefon oder provider:value); Org-/Deal-/User-/Task-Beziehungen bleiben unberührt, aber ein übergebenes identifiers-Array ERSETZT die Messaging-Kanäle des Contacts (nicht gelistete werden entkoppelt). | ||
update_organizations | Partial-Update per ID. Fasst Beziehungen nie an. | ||
update_deals | Partial-Update per ID, inklusive singleSelect-Custom-Column-Werten und services (Inline-Array aus {serviceId, quantity}, das die komplette Service-Menge des Deals ERSETZT); Org-/User-/Contact-/Task-Beziehungen bleiben unberührt (nutzen Sie manage_record_links). | ||
update_services | Partial-Update per ID. | ||
update_tasks | Partial-Update per ID, inklusive singleSelect-Custom-Column-Werten. Fasst Beziehungen nie an. | ||
update_record_notes | Markdown-Notes auf 1 bis 100 Records ersetzen oder anhängen, gewählt über mode. | ||
manage_record_links | IDs auf einer Beziehung hinzufügen oder entfernen (action add oder remove). Der einzige Weg, Beziehungen zu ändern. | ||
delete_records | ✓ | IRREVERSIBLES Hard-Delete von 1 bis 100 Records per ID (Contacts auch per E-Mail, Telefon oder provider:value). |
Alle Create- und Update-Tools nehmen Custom-Column-Werte über customFieldValues; rufen Sie zuerst get_record_schema für die Column-IDs auf.
| Tool | Read | Destructive | Zweck |
|---|---|---|---|
get_workspace_context | ✓ | Ihr User, das Company-Profil, alle Rollen inklusive Rechte und Ihre verbundenen Messaging-Konten (Ihre eigenen plus die mit dem Workspace geteilten) in einem Call. Der natürliche erste Call einer Session. | |
list_users | ✓ | Teammitglieder mit ID, Name, E-Mail, roleId und Status. |
Die Messaging-Tools sind ab dem Pro-Tarif verfügbar.
| Tool | Read | Destructive | Zweck |
|---|---|---|---|
get_messaging_threads | ✓ | Zwei Modi: ohne threadId listet es Inbox-Threads mit Filtern und Sortierung (Threads ohne Nachricht werden ausgeblendet, außer sie enthalten einen Draft); mit threadId liefert es einen Thread plus eine Seite seiner Nachrichten (Standard 25, neueste zuerst, Drafts inklusive). | |
get_activities | ✓ | Aktivitäts-Timeline (Nachrichten, Audit-Log-Änderungen, LinkedIn-Account-Aktivitäten und Kalenderereignisse) für den Workspace oder einen Record. | |
get_calendars | ✓ | Drei Modi: list: "calendars" (Standard) listet die Kalender der zugänglichen verbundenen Konten; list: "events" listet Kalenderereignisse sortiert nach Startzeit, filterbar nach calendarId oder einem startsAt-Zeitraum; mit eventId liefert es die Details eines Ereignisses inklusive Organisator und Teilnehmern. Die Ids entsprechen der entityId der Kalender-Webhook-Events. | |
send_chat_message | Stellt sofort zu. Mit threadId antwortet es in einem bestehenden Chat; mit connectedAccountId plus attendeeIdentifiers startet es einen neuen (optionales chatName benennt eine Gruppe). Neue LinkedIn-Chats sind standardmäßig Classic; setzen Sie linkedinProduct auf sales_navigator oder recruiter für ein InMail (braucht inmailSubject), oder inmail:true, um auf Classic jemanden außerhalb Ihres Netzwerks per InMail anzuschreiben. | ||
send_email | Stellt sofort zu. Senden oder antworten von einem verbundenen E-Mail-Konto; kann einen gespeicherten Draft über draftMessageId senden. | ||
save_message_draft | Antwort zur Durchsicht vorbereiten: Der Draft erscheint in der Inbox-Compose-Box, und Sie senden ihn selbst. Drafts hängen am Thread, einer pro Thread, erneutes Speichern aktualisiert ihn. | ||
discard_message_draft | ✓ | Draft per Draft-Message-ID löschen. | |
update_messaging_thread | Thread-State setzen: unread, open, closed oder spam. | ||
connect_messaging_account | Erzeugt einen Link, den der User im Browser öffnet, um einen Kanal zu verbinden (WhatsApp, LinkedIn, E-Mail, Instagram, Telegram). Sie geben den Link zurück; der User schließt die Auth dort ab. Läuft nach 30 Minuten ab. |
| Tool | Read | Destructive | Zweck |
|---|---|---|---|
get_social_posts | ✓ | Posts auf LinkedIn oder Instagram, gelesen über ein verbundenes Konto. Listet die Posts beliebiger Nutzer über authorIdentifier (ein Public Identifier oder eine Provider-Member-ID, z. B. aus dem LinkedIn-Kanal eines Kontakts; Standard ist me, der Kontoinhaber) oder holt einen einzelnen Post per postId. | |
get_social_post_engagement | ✓ | Engagement zu einem Post: kind=comments (Standard) listet Kommentare, kind=reactions wer reagiert hat; mit commentId die Reaktionen auf diesen Kommentar. | |
get_social_profile | ✓ | Ein LinkedIn- oder Instagram-Profil einer Person oder eines Unternehmens per identifier (der /in/<slug>- oder /company/<slug>-Teil der Profil-URL, eine Provider-ID oder me); liefert Name, Headline, Ort, Zähler und Netzwerkdistanz, soweit verfügbar, plus einen Typ, der Person und Organisation unterscheidet. | |
manage_social_relations | Kontaktanfragen: Einladungen listen (standardmäßig erhaltene, oder Ihre eigenen gesendeten/ausgehenden über direction), invite (sendet eine echte Anfrage), accept oder cancel per invitationId. | ||
linkedin_search_sales_leads | ✓ | Findet Personen über LinkedIn Sales Navigator: entweder aus einer eingefügten Such-URL oder als strukturierte Suche mit Filtern (Keywords, Standort, Branche, Unternehmen, Jobtitel, Seniorität und mehr). Lead-Zeilen enthalten die aktuellen Positionen (Unternehmen, Rolle und Unternehmens-ID, nutzbar mit get_social_profile). Braucht ein Sales-Navigator-Abo. | |
linkedin_search_sales_companies | ✓ | Findet Unternehmen über LinkedIn Sales Navigator: entweder aus einer eingefügten Unternehmens-Such-URL oder als strukturierte Suche mit Filtern (Keywords, Standort, Branche, Mitarbeiterzahl, Jahresumsatz und mehr). Braucht ein Sales-Navigator-Abo. | |
linkedin_get_sales_search_parameters | ✓ | Löst die IDs hinter den LinkedIn-Sales-Navigator-Sucheingaben nach Typ auf (Standorte, Branchen, Jobtitel, Funktionen, Unternehmen, Schulen, Gruppen und mehr) plus Ihre Lead-/Account-Listen und gespeicherten/letzten Suchen; Keyword ist optional, ein reiner Typ zählt also die ganze Familie auf. | |
linkedin_manage_sales_lists | LinkedIn-Sales-Navigator-Lead- und -Account-Listen: Listen aufzählen, die Mitglieder einer Liste lesen oder einen Lead bzw. ein Unternehmen in eine bestehende Liste speichern. Neue Listen entstehen in Sales Navigator selbst. |
| Tool | Read | Destructive | Zweck |
|---|---|---|---|
search_docs | ✓ | Volltextsuche über die Docs; standardmäßig nur die Produkt-Guides (source=docs); mit source=api oder all auch die REST-API-Referenz. Liefert Slug, Source, Titel, URL, Snippet. | |
get_docs_page | ✓ | Eine Doku-Seite als Markdown inklusive kanonischer URL. Listet bei einem Miss alle gültigen Slugs. | |
search | ✓ | Von ChatGPT-Deep-Research-Connectors verlangt; föderiert CRM-Records und Docs. Interaktive Agents nehmen besser search_records oder search_docs. | |
fetch | ✓ | Deep-Research-Gegenstück zu search: holt ein Ergebnis per ID. |
| Tool | Read | Destructive | Zweck |
|---|---|---|---|
manage_custom_columns | ✓ | Ein Tool mit action-Schalter: list, upsert (anlegen oder aktualisieren), delete. Deckt alle zehn Spaltentypen ab; type und entityType sind beim Update unveränderlich. Delete ist IRREVERSIBLE und löscht alle gespeicherten Werte. |
| Tool | Read | Destructive | Zweck |
|---|---|---|---|
manage_widgets | ✓ | Ein Tool mit action-Schalter: list, get, create, update, delete. Die get-Action liefert die berechneten Datenpunkte zur Konfiguration dazu, aggregierte Summen kommen also direkt aus einem Widget. |
| Tool | Read | Destructive | Zweck |
|---|---|---|---|
manage_webhooks | ✓ | Ein Tool mit action-Schalter: list, get, create, update, delete, dazu das Delivery-Log (Action list_deliveries, auf die aktuelle url eines Webhooks beschränkt, wenn Sie dessen id übergeben) und die erneute Zustellung (Action resend_delivery). |
| Tool | Read | Destructive | Zweck |
|---|---|---|---|
update_workspace_settings | target profile aktualisiert Ihren Namen, Ihr Land und Ihren Avatar; target company aktualisiert die Workspace-Währung (nur Admins). | ||
manage_team | Mitglieder per E-Mail einladen (Action invite, bis 20, verschickt echte Einladungs-E-Mails) oder Rolle und Status eines Mitglieds ändern (Action update_member). |
| Tool | Read | Destructive | Zweck |
|---|---|---|---|
request_support | Öffnet ein Support-Ticket beim Customermates-Team (Betreff plus Beschreibung). Das Team meldet sich per E-Mail und im In-App-Chat. Gibt die Ticketnummer zurück. |
Alle 46 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,messagingKeys: records, workspace, messaging, social, docs, custom-columns, widgets, 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.
delete_records und vor jedem Send-Tool beim User rückzuversichern.manage_record_links. Die Update-Tools fassen Beziehungen nie an, und null auf einem Relationship-Array wird serverseitig mit Remediation-Hint abgelehnt.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. Drafts hängen am Thread; eine komplett neue ausgehende Nachricht lässt sich nicht als Draft anlegen.destructiveHint: true und den Präfix IRREVERSIBLE in der Beschreibung.filters-Feld enthält ein konkretes JSON-Beispiel.