MCP-Tool-Suite für ein CRM entwerfen: 4 Lektionen - Relaticle         

MCP-Tool-Suite für ein CRM entwerfen: vier Lektionen
====================================================

Was uns der Bau des MCP-Servers von Relaticle über Schemas, gemeinsame Validierung benutzerdefinierter Felder, Autorisierung und Client-Erkennung beigebracht hat.

 Manuk Minasyan · 11. September 2026 · 11 Min. Lesezeit

 ![MCP-Tool-Suite für ein CRM entwerfen: vier Lektionen](https://relaticle.com/storage/ink/01M7T44DV2SM1BF55EMB20ZJK1.png) 

Wir haben den MCP-Server von Relaticle auf den bestehenden Schreibaktionen des CRM aufgebaut. Vier Lektionen haben ihn geprägt: explizite Schemas, gemeinsame Validierung, klare Autorisierung und zuverlässige Client-Erkennung. Benutzerdefinierte Felder werden im Chat und in MCP unterschiedlich beschrieben, aber beide normalisieren Eingaben über denselben Service. Der Server deckt jeden CRM-Eintragstyp ab, dazu Arbeitsbereichskontext und Uploads. Verbindungen mit E-Mail-Zugriff erhalten außerdem E-Mail-Tools.

Nichts davon ergab sich aus der MCP-Spezifikation allein. Hier steht, was wir beim Bauen tatsächlich herausgefunden haben.

![Frühere MCP-Tool-Familien, bevor Datei-Uploads hinzukamen](https://relaticle.com/storage/ink/01M12RRDBW8CWGZR6CNZFZ8VWN.png)

*Ältere Grafik vom August 2026. Der aktuelle Server enthält zusätzlich `upload-file` und `create-upload-url`.*

[](#die-tool-familien-und-warum-sie-nicht-symmetrisch-sind "Permalink")Die Tool-Familien und warum sie nicht symmetrisch sind
-----------------------------------------------------------------------------------------------------------------------------

| Tool-Familie | Anzahl | Designentscheidung |
|---|---|---|
| CRUD für Unternehmen / Personen / Verkaufschancen | 15 (5 × 3) | Nur List, Get, Create, Update, Delete. Beziehungen sind einfache Fremdschlüssel (`company_id`, `contact_id`), die beim Erstellen und Aktualisieren direkt validiert werden. Ein eigenes Attach-Tool ist nicht nötig |
| CRUD für Aufgaben / Notizen + Beziehungen | 14 (7 × 2) | Dieselben fünf, dazu Attach/Detach. Aufgaben und Notizen sind polymorphe n:m-Verknüpfungen zu Unternehmen, Personen und Verkaufschancen (Aufgaben haben zusätzlich Zuständige). Ein einzelnes Fremdschlüsselfeld kann diese Beziehung nicht abbilden |
| Arbeitsbereich und Utilities über mehrere Entitäten | 10 | `search`, `fetch`, Kontodaten, fünf lesende Arbeitsbereichs-Tools sowie die Tools `upload-file` und `create-upload-url` |

Die Tool-Familien haben unterschiedliche Aufgaben. Beziehungen von Unternehmen, Personen und Verkaufschancen laufen über Felder beim Erstellen und Aktualisieren. So kann eine Verkaufschance auf ein Unternehmen verweisen. Beziehungen von Aufgaben und Notizen sind assoziativ: Eine Aufgabe kann drei Unternehmen und zwei Personen gleichzeitig betreffen, deshalb haben sie eigene Sync-Endpunkte. Attach/Detach haben wir den anderen drei nicht der Einheitlichkeit halber hinzugefügt. Es gibt dort nichts, woran etwas angehängt werden könnte.

[](#search-und-fetch-sind-ein-vertrag-kein-komfortmerkmal "Permalink")Search und Fetch sind ein Vertrag, kein Komfortmerkmal
----------------------------------------------------------------------------------------------------------------------------

`search` und `fetch` sind keine beliebigen Tools, die zufällig so heißen. Sie sind genau das Paar, das der Company-Knowledge-Konnektor von ChatGPT verlangt: ein Client, der Einträge per Suchanfrage findet und über eine stabile URL belegt. Beide tragen die Attribute `#[Name('search')]` und `#[Name('fetch')]`, damit der im Protokoll übertragene Name unabhängig vom Klassennamen stimmt. Beide sind in ihren MCP-Tool-Annotationen als schreibgeschützt, idempotent und geschlossen (closed-world) festgelegt.

Beim ersten Anlauf haben wir den Vertrag falsch umgesetzt. `search` lieferte URLs wie `/app/{segment}/{id}` und ließ den Arbeitsbereichs-Slug weg, den das Routing von Filament tatsächlich verlangt. Jede Quellen-URL lief deshalb in einen 404, auch für den Inhaber des Eintrags. `fetch` konnte nur genau diese fehlerhafte Form lesen und lehnte daher auch die echte URL ab, die jemand aus der Adressleiste seines Browsers kopiert. Aufgaben und Notizen hatten gar keine eigene Seite pro Eintrag. Zwei der fünf durchsuchbaren Entitätstypen hatten also von vornherein keine URL, die sich als Quelle angeben ließ.

Die Lösung war `CanonicalRecordUrl`: eine Klasse, die das URL-Format sowohl erzeugt als auch zerlegt und von beiden Tools genutzt wird. Wer Erzeugen und Zerlegen auf zwei Dateien verteilt, lässt beide auseinanderlaufen. Ein Suchergebnis, das ein Client nicht wieder in fetch einfügen kann, ist schlechter als gar kein Beleg.

[](#schema-beschreibungen-sind-prompts-keine-dokumentation "Permalink")Schema-Beschreibungen sind Prompts, keine Dokumentation
------------------------------------------------------------------------------------------------------------------------------

Die Schemas der Create- und Update-Tools verwenden für `custom_fields` diese Anweisung:

> „Werte benutzerdefinierter Felder als Schlüssel-Wert-Paare. WICHTIG: Sie MÜSSEN zuerst die Ressource crm-schema lesen, um die gültigen Feldcodes für diesen Entitätstyp zu ermitteln. Unbekannte Feldcodes werden abgelehnt. Verwenden Sie exakt die Feldcodes aus dem Schema (z. B. 'job\_title', nicht 'jobTitle').“

Das ist keine API-Dokumentation. Es ist eine Anweisung an einen Agenten mitten in einer Aufgabe. Sie soll zwei Fehler verhindern, die Modelle tatsächlich machen. Modelle raten einen plausibel klingenden Feldcode, statt ihn nachzuschlagen. Außerdem schreiben sie Schlüssel in snake\_case in camelCase um, weil diese Konvention in den Trainingsdaten häufiger vorkommt. Die Tool-Beschreibungen geben dieselbe Anleitung auf allgemeinerer Ebene: „Erstellen Sie ein neues Unternehmen im CRM. Nutzen Sie die Ressource crm-schema, um verfügbare benutzerdefinierte Felder zu ermitteln.“ Diese Beschreibungen verweisen das Modell auf die Schema-Ressource der jeweiligen Entität (`relaticle://schema/company`, ein URI pro Entität), noch bevor es das Tool aufruft.

Das funktioniert nur, weil sich die Schema-Ressource günstig lesen lässt und pro Arbeitsbereich 60 Sekunden lang zwischengespeichert wird. Wäre die Ermittlung bei jedem Feldzugriff ein weiterer Datenbank-Roundtrip, würden wir versuchen, das gesamte Schema in jede Tool-Beschreibung einzubetten. Die Token-Kosten würden dann bei jedem einzelnen Aufruf anfallen statt einmal pro Lesezugriff auf die Ressource.

[](#unterschiedliche-beschreibungen-gemeinsame-normalisierung-benutzerdefinierter-felder "Permalink")Unterschiedliche Beschreibungen, gemeinsame Normalisierung benutzerdefinierter Felder
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Benutzerdefinierte Felder gehören zum jeweiligen Arbeitsbereich. Der `CustomFieldsSchemaDescriber` des Chats zeigt Feldcodes und Optionsbezeichnungen im Tool-Schema an. Das `CustomFieldSchema` von MCP liefert strukturierte Definitionen mit Bezeichnungen und Options-IDs.

Beide Schreibwege rufen `CustomFieldInput::normalize()` auf, bevor `ValidCustomFields` das Ergebnis validiert. Auswahlfelder akzeptieren Optionsbezeichnungen oder IDs. Mehrdeutige Bezeichnungen scheitern an der Validierung, daher löst eine Options-ID Fälle mit doppelten Bezeichnungen auf.

Das Enum `CustomFieldType` verwaltet die Eingabeformate und Beispiele, die beide Schema-Beschreibungen nutzen. Der Rich-Editor akzeptiert Werte in Markdown oder HTML und speichert sie als HTML.

Diese Grenze hält die Darstellung clientspezifisch und zentralisiert die Normalisierung. Ein neues Feld braucht in keinem Tool einen handgeschriebenen Schema-Slot.

[](#batching-gehört-zur-freigabe-oberfläche-nicht-zum-protokoll "Permalink")Batching gehört zur Freigabe-Oberfläche, nicht zum Protokoll
----------------------------------------------------------------------------------------------------------------------------------------

Unsere Lösch-Tools sehen unterschiedlich aus, je nachdem, welcher Client sie aufruft. Das ist eine bewusste Designentscheidung und keine Abweichung. Das Chat-Lösch-Tool akzeptiert mit `ids: string[]` eine oder mehrere IDs. Sein Docstring erklärt: „Übergeben Sie eine ID, um ein einzelnes Unternehmen zu löschen, oder mehrere, um alle in einem Aufruf zu löschen.“ Eine Anfrage mit mehreren IDs wird zu einer einzigen `PendingAction`, die ein Mensch als Teil eines Plans prüft. Dabei sind Sammelentscheidungen pro Eintrag möglich. Das Modell schickt also nicht drei getrennte Löschaufrufe ab, die jeweils eine eigene Freigabe verlangen.

Die MCP-Lösch-Tools nehmen eine einzelne skalare `id`. Es gibt keinen Freigabeschritt, für den sich Aufrufe bündeln ließen: Ein MCP-Schreibzugriff wird sofort ausgeführt, sobald der OAuth-Token die Berechtigungsprüfung besteht. Es gibt also nichts, was dem Ziel entspricht, die Zahl der Karten zu verringern, die ein Mensch durchklicken muss. Für einen Agenten, der in großem Umfang aufräumt, ist das eine echte Lücke (zwölf veraltete Verkaufschancen zu löschen bedeutet heute zwölf Aufrufe). Wir halten es nicht für offensichtlich richtig. Es ist die Entscheidung, die wir getroffen haben, weil wir das Muster nie überprüft haben, nachdem es auf der Chat-Seite existierte.

[](#token-berechtigungen-und-benutzerautorisierung-sind-getrennte-prüfungen "Permalink")Token-Berechtigungen und Benutzerautorisierung sind getrennte Prüfungen
---------------------------------------------------------------------------------------------------------------------------------------------------------------

Ein MCP-Schreibzugriff muss zwei getrennte Fragen beantworten, bevor er die Datenbank berührt: Erlaubt dieser Token die Operation, und darf dieser Benutzer den Eintrag ändern. Beide Prüfungen laufen absichtlich an verschiedenen Stellen.

`ChecksTokenAbility` übernimmt die erste und muss OAuth als Sonderfall behandeln. Ein persönlicher Zugriffstoken von Sanctum kann fein abgestufte Berechtigungen tragen (`read`, `create`, `update`, `delete`). Ein OAuth-Token von Passport, wie ihn Claude oder ChatGPT tatsächlich hält, kann dagegen nur `mcp:use` anfordern, denn das ist der einzige Scope, den [laravel/mcp](https://github.com/laravel/mcp) in den Metadaten seines Autorisierungsservers veröffentlicht. Berechtigungen pro Fähigkeit lassen sich bei OAuth nicht ausdrücken. `mcp:use` autorisiert also das gesamte Toolset. Auf welche Daten welches Arbeitsbereichs diese Tools zugreifen können, wird separat am Token selbst festgelegt.

Diese Bindung übernimmt `SetApiWorkspaceContext`. OAuth-Tokens tragen eine maßgebliche `workspace_id`, und die Middleware ignoriert für diese Tokens den Header `X-Workspace-Id`. Sie setzt den Tenant-Kontext und den Web-Guard und wendet dann `WorkspaceScope` auf Modelle mit Scope an. Ihre Methode `terminate()` hebt diese Scopes wieder auf. Die Middleware unterstützt ausdrücklich FPM und nicht Octane, weil ihr statischer Modellzustand unter Octane ein fehlgeschlagenes Aufräumen überleben kann.

Keine dieser beiden Prüfungen stellt fest, ob ein Fremdschlüssel im Request-Body tatsächlich zum Arbeitsbereich des Aufrufers gehört. Das erledigt `TenantFkValidator::assertOwned()`, aufgerufen in der Aktion selbst. `CreateOpportunity` prüft vor dem Einfügen, dass `company_id` und `contact_id` existieren und zum Arbeitsbereich des Aufrufers gehören, unabhängig davon, was die Middleware bereits eingegrenzt hat. Ein Token mit `mcp:use` und gültiger Arbeitsbereichsbindung kann also keine neue Verkaufschance auf eine Unternehmens-ID zeigen lassen, die er aus den Daten eines fremden Tenants erraten hat. So tief im Schreibpfad vertraut nichts allein dem Scoping.

[](#tool-annotationen-legen-richtlinien-fest-und-eine-von-hand-gepflegte-liste-läuft-auseinander "Permalink")Tool-Annotationen legen Richtlinien fest, und eine von Hand gepflegte Liste läuft auseinander
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Die [Tool-Annotationen](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool-annotations) von MCP (`readOnlyHint`, `idempotentHint`, `destructiveHint`, `openWorldHint`) sind keine Dekoration. Die Prüfungen bei der Verzeichniseinreichung von Claude und ChatGPT lesen sie, und ein Client kann mit `destructiveHint` sinnvoll entscheiden, ob er vor einem Tool-Aufruf nachfragt. Wir annotieren jedes Tool: Lesende Tools sind als schreibgeschützt und idempotent markiert. Updates, Löschungen und Detach-Aufrufe tragen, wo es passt, destruktive Hinweise. Aufgaben-Schreibzugriffe, die Benachrichtigungen senden, und Datei-Uploads deklarieren Open-World-Verhalten.

Trotzdem haben wir eine Lücke ausgeliefert. Die erste Version unseres Annotationstests prüfte bestimmte Erwartungen an einer handverlesenen Liste von Tool-Klassen. `WhoAmiTool` wurde dieser Liste nie hinzugefügt. So deklarierten 31 der damals 32 Tools `openWorldHint`. Beim 32. Tool fehlte diese Annotation unbemerkt, während der Test grün blieb. Die Lösung war keine größere Liste. Wir lesen jetzt per Reflection `RelaticleServer::$tools` selbst aus und prüfen die Eigenschaft an jeder Klasse, die dort tatsächlich registriert ist. So kann ein neues Tool die Prüfung nicht umgehen, nur weil niemand daran gedacht hat, es in ein Dataset aufzunehmen:

```
$tools = (new ReflectionClass(RelaticleServer::class))->getDefaultProperties()['tools'];
foreach ($tools as $toolClass) {
    expect(app($toolClass)->annotations())->toHaveKey('openWorldHint');
}

```

Dieselbe Lektion, dass die Grenze weiter reicht, als man denkt, zeigte sich auch auf der Transportebene. Ist `MCP_DOMAIN` gesetzt, liegt der MCP-Server im Root einer Subdomain, und dieses Root ist zugleich seine OAuth-Kennung als geschützte Ressource. Clients nach RFC 9728 ermitteln diese Kennung, indem sie die nackte URL per `GET` abrufen und jede 200-Antwort als Metadatendokument der geschützten Ressource behandeln. Unsere Root-Route lieferte dort ein HTML-Infobanner. Ein Client auf rmcp-Basis (bei uns Codex) las das Banner als Metadaten, fand darin kein Feld `resource` und scheiterte mit der ziemlich kryptischen Meldung „Protected resource metadata missing required resource field.“ Claude und ChatGPT sind nie darauf gestoßen, weil ihr SDK nur Pfade unter `/.well-known` abruft. Deshalb blieb der Fehler unbemerkt. Die Lösung kehrt den Standard um: Ein nacktes GET erhält jetzt die korrekte Protokollantwort, und das Banner wird nur bei einer echten Navigation des Browsers auf oberster Ebene angezeigt. Erkannt wird sie über `Sec-Fetch-Mode: navigate`, ein Signal für Browser-Navigation. Auch Nicht-Browser-Clients können diesen Header senden, er ist also keine Authentifizierungskontrolle.

[](#was-wir-anders-machen-würden "Permalink")Was wir anders machen würden
-------------------------------------------------------------------------

Ursprünglich pflegten wir getrennte Übersetzungswege für benutzerdefinierte Felder. Die aktuelle Umsetzung teilt die Normalisierung über `CustomFieldInput` und die Formatbeschreibungen über `CustomFieldType`. Das reduziert Abweichungen zwischen den Implementierungen. Gleichzeitig kann der Chat Bezeichnungen in den Vordergrund stellen, während MCP strukturierte Definitionen bereitstellt. Wenn sich die unterstützten Wertformate ändern, sollten Tests weiterhin prüfen, ob beide Schemas übereinstimmen.

Wir würden auch das Batching beim MCP-Löschen jetzt überdenken, statt es als Asymmetrie stehen zu lassen, die uns erst beim Schreiben dieses Textes aufgefallen ist. Es war richtig, zuerst Löschungen einzelner Einträge auszuliefern und das Freigabe-Batching auf der Chat-Seite sauber zu lösen, wo die UX-Kosten fehlenden Batchings sofort sichtbar waren. Aber ein Agent, der ein CRM in großem Umfang aufräumt, ist ein realer MCP-Anwendungsfall, und heute zahlt er dafür mit der Zahl der Aufrufe, ohne dass es mehr Sicherheit bringt. Die OAuth-Scope-Prüfung wird nicht gründlicher, wenn man sie zwölfmal statt einmal ausführt.

Wenn Sie einen MCP-Server für Produktionsdaten bauen, hat sich bei uns folgendes Muster am besten bewährt. Leiten Sie jeden Schreibzugriff durch dieselben Aktionsklassen, die Ihre Web-App bereits nutzt. Behandeln Sie das MCP-Tool als dünne Übersetzungsschicht darüber. Schema hinein, validierter Aufruf der Aktion, Ressource zurück. Alles andere, also Annotationen, Erkennung benutzerdefinierter Felder und kanonische URLs, ist protokollgeprägtes Beiwerk auf demselben Kern. Die vollständige Tool-Liste und die Einrichtungsanleitung finden Sie unter [/developers/mcp](https://relaticle.com/de/developers/mcp). Die Sicht für Anwender auf denselben Server bieten [Claude per MCP mit Ihrem CRM verbinden](https://relaticle.com/de/blog/claude-per-mcp-mit-ihrem-crm-verbinden) und [was agentennativ wirklich bedeutet](https://relaticle.com/de/blog/was-agent-native-crm-wirklich-bedeutet).

 Mit Tag [ #mcp ](https://relaticle.com/de/blog/tag/mcp) 

 Auf dieser Seite

 Weiterlesen

 Ähnliche Beiträge. 
--------------------

- [  2. Nov 2026  Engineering 

    ###  Gratis-Testphase für Premium-KI-Modelle missbraucht: Was wir geändert haben 

    Eine Testphase ohne Karte, die Premium-KI-Modelle freischaltete, zog Konten an, die das CRM nie nutzten. Statt einer Karte binden wir Premium-Modelle jetzt an den ersten echten Eintrag.

     ![](https://relaticle.com/storage/ink/01M7T550NZ8B741RHVHRD49WGG.png) 

     ](https://relaticle.com/de/blog/testphase-fuer-premium-ki-modelle-missbraucht-was-wir-geaendert-haben)
- [  21. Okt 2026  Engineering 

    ###  php2shell: So haben wir Relaticle gepatcht und so patchen Sie Ihre Installation 

    php2shell sind zwei kritische PHP-Lücken, die einem Angreifer Code-Ausführung auf einem Webserver erlauben. Was wir bei Relaticle Cloud gepatcht haben und was eine selbst gehostete Installation heute tun muss.

     ![](https://relaticle.com/storage/ink/01M7T57VSBHK529MVHPP1NKRBF.png) 

     ](https://relaticle.com/de/blog/php2shell-php-in-docker-und-forge-patchen)
- [  22. Sep 2026  Engineering 

    ###  Benutzerdefinierte Felder, die überall funktionieren, ohne Code pro Feld 

    So macht Relaticle benutzerdefinierte Felder in Formularen, APIs, Chat und MCP verfügbar: mit gemeinsamer Normalisierung, klarer Semantik für leere Werte und ausdrücklichen Grenzen.

     ![](https://relaticle.com/storage/ink/01M7T4JZV14ZXNAG3BW39JW7V0.png) 

     ](https://relaticle.com/de/blog/benutzerdefinierte-felder-ueberall-ohne-code-pro-feld)
