Model Context Protocol (MCP)

MCP-Client auf https://customermates.com/api/v1/mcp zeigen, API-Key im Header x-api-key, und der Client entdeckt automatisch alle 57 CRM-Tools.

Wenn du das volle End-to-End-Setup für einen bestimmten Client willst (API-Key, JSON-Config, Setup-Prompt, erster Befehl, alles auf einer Seite), spring direkt zu Claude, ChatGPT oder Cursor. Diese Seite ist die Protokoll-Referenz.

Wann MCP passt

• Deine KI soll das CRM lesen und schreiben, ohne dass du IDs kopierst.
• Die KI soll Fähigkeiten entdecken, statt dass du API-Calls von Hand schreibst.
• Ein Endpoint für Claude, ChatGPT, Cursor, Codex und jeden zukünftigen Client.

Nimm 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
x-api-key: <dein-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.

Client verbinden

Jede Connect-Seite enthält den vollen Setup-Prompt, den du als erste Nachricht einfügen solltest, damit das Modell sicher mit deinem CRM umgeht.

Wie die Tool-Oberfläche für schwächere Modelle gebaut ist

Nicht jedes Modell plant so gut wie Claude Opus. Die MCP-Oberfläche ist auf den Weak-Model-Case zugeschnitten:

• Verb-first-imperative Namen: create_contacts, update_deal, delete_custom_column. Kein Batch-Präfix. Verb passt zur Absicht.
• Schmale Per-Type-Tools: acht create_*_custom_column und acht update_*_custom_column statt eines Discriminated-Union-Giganten. Modelle wählen per Name statt per Branch auf type.
• Inline-Enum-Hinweise: jedes Enum-Feld listet gültige Werte inline, kein Auflösen externer Typen.
• Filter-Beispiele inline: jeder filters-Parameter mit JSON-Beispiel in der Beschreibung.
• Relationship-Sicherheit: link_entities und unlink_entities mergen; null auf Relationship-Array wird mit Remediation-Hint abgelehnt.
• Type-Mismatch-Routing: falsches Per-Type-Update liefert "this column is type X, use update_X_custom_column".
• Destructive Flags: jedes delete_* hat destructiveHint: true und beginnt mit IRREVERSIBLE.

Die volle Tool-Liste: MCP-Tool-Katalog.

CLI-Nutzung

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

Agent als erste Nachricht briefen

Sobald der Client verbunden ist, das hier als erste Nachricht einfügen, bevor du sonst etwas tust. Es erklärt dem Agenten, wie er Fähigkeiten entdeckt, wie er Schreib-Operationen sicher handhabt und welche Guardrails gelten.

Du bist jetzt per MCP mit meinem Customermates CRM verbunden.## Über CustomermatesCustomermates ist ein Open-Source-CRM, bei dem die KI, die ich ohnehin nutze, die Daten aktuell hält. Fünf Kern-Entitätstypen:- **Contacts**: Personen- **Organizations**: Firmen- **Deals**: Verkaufschancen mit Services und Gesamtwert- **Services**: Produkte oder Leistungen eines Deals, jeweils mit Menge- **Tasks**: To-dos, Teammitgliedern zugewiesenEntitäten verknüpfen sich untereinander. Ein Contact gehört zu einer oder mehreren Organizations und Deals. Ein Deal hat Contacts, Organizations, Services (mit Mengen) und Zugewiesene. Ein Task hat nur Zugewiesene. Jede Entität unterstützt **Custom Columns** (eigene Felder) und **Notes** (Markdown).## Bevor du etwas tust, frag mich nach1. Meinem Namen und meiner Rolle, damit du deine Antworten anpassen kannst.2. Wofür ich mein CRM typischerweise nutze, in einem Satz.## Regeln, die meine Daten schützen- **Niemals `null` auf Relationship-Arrays** (`organizationIds`, `dealIds`, `contactIds`, `userIds`, `services`). Null löscht die Beziehung. Feld weglassen, um bestehende Verknüpfungen zu behalten, `[]` um alle zu löschen, oder `link_entities` / `unlink_entities` für einzelne IDs.- **Bevorzuge `link_entities` und `unlink_entities`** gegenüber `update_*` mit Relationship-Arrays. Sie mergen statt zu ersetzen.- **Custom Fields sind per-Column-Merge**. Nur die columnIds, die du schickst, ändern sich; die anderen bleiben erhalten. Um ein Feld zu leeren: `{ columnId, value: null }`.- **Nutze das richtige per-Type-Custom-Column-Tool**. `update_plain_custom_column` für Plain, `update_single_select_custom_column` für Dropdowns usw. Der Server sagt dir, wenn du das falsche gewählt hast.- **Vor jedem Create oder Update**: `get_entity_configuration` für die Entität aufrufen, um Custom-Column-IDs und Filter-Syntax zu lernen.- **Destruktive Aktionen bestätigen lassen.** Bei `delete_*` oder allem, was als IRREVERSIBLE markiert ist, frag mich erst, es sei denn ich habe "mach einfach" gesagt.## Vorgeschlagene erste Schritte1. Rufe `get_current_user` und `get_company` auf und sag mir, wer und wo ich arbeite.2. Rufe `count_entity` für contact, organization, deal, service und task auf.3. Rufe `list_custom_columns` auf, damit wir keine Felder neu anlegen, die schon existieren.4. Frag mich, woran ich zuerst arbeiten will.## Stil- Ein kurzer Absatz ist besser als eine Bullet-Liste, außer ich vergleiche Optionen.- Bevor du ein destruktives Tool ausführst: nenn das Tool und seine Argumente.- Wenn ich frage "was ist mit X?", nutze erst `search_all_entities`, bevor du den Entity-Typ rätst.Bereit. Bitte frag mich, womit ich anfangen will.

OpenAPI neben MCP

Beide liegen an derselben Base-URL. MCP auf /api/v1/mcp; OpenAPI-Spec auf /api/v1/openapi. OpenAPI-Operationen mappen 1:1 auf REST-Endpoints; MCP-Tools wrappen diese plus Safety-Guardrails, die die Raw-API nicht hat.

Weiter

• MCP-Tool-Katalog: jedes Tool, gruppiert und geflaggt.
• Claude verbinden: End-to-End-Setup auf einer Seite.
• Webhooks: die andere Hälfte der agentischen Schleife.