Concevoir une suite d'outils MCP pour un CRM - Relaticle         

Concevoir une suite d'outils MCP pour un CRM : quatre leçons
============================================================

Ce que la construction du MCP server de Relaticle nous a appris sur les schémas, la validation partagée des champs personnalisés, l'autorisation et la découverte côté client.

 Manuk Minasyan · 11 septembre 2026 · 13 min de lecture

 ![Concevoir une suite d'outils MCP pour un CRM : quatre leçons](https://relaticle.com/storage/ink/01M7T44GJS4JSH7RBXV0WGPN3S.png) 

Nous avons construit le MCP server de Relaticle autour des actions d'écriture que le CRM possédait déjà. Quatre leçons l'ont façonné : des schémas explicites, une validation partagée, une autorisation claire et une découverte fiable côté client. Les champs personnalisés sont décrits différemment dans le chat et dans MCP, mais les deux normalisent les entrées avec le même service. Le serveur couvre tous les types d'enregistrement du CRM, le contexte de l'espace de travail et les téléversements. Les connexions avec accès à la messagerie reçoivent aussi des outils e-mail.

Rien de tout cela ne ressortait de la seule lecture de la spécification MCP. Voici ce que nous avons réellement découvert en l'implémentant.

![Familles d'outils MCP historiques, avant l'ajout des téléversements de fichiers](https://relaticle.com/storage/ink/01M12RRDBW8CWGZR6CNZFZ8VWN.png)

*Schéma historique d'août 2026. Le serveur actuel comprend aussi `upload-file` et `create-upload-url`.*

[](#les-familles-doutils-et-pourquoi-elles-ne-sont-pas-symétriques "Permalink")Les familles d'outils, et pourquoi elles ne sont pas symétriques
-----------------------------------------------------------------------------------------------------------------------------------------------

| Famille d'outils | Nombre | Choix de conception |
|---|---|---|
| CRUD entreprises / personnes / opportunités | 15 (5 × 3) | Uniquement List, Get, Create, Update et Delete. Les relations sont des clés étrangères simples (`company_id`, `contact_id`) validées directement à la création et à la mise à jour, donc aucun outil d'association distinct n'est nécessaire |
| CRUD tâches / notes + relations | 14 (7 × 2) | Les mêmes cinq, plus Attach/Detach. Les tâches et les notes ont des relations polymorphes plusieurs-à-plusieurs avec des entreprises, des personnes et des opportunités (les tâches ont en plus des assignés), donc un seul champ de clé étrangère ne peut pas exprimer la relation |
| Utilitaires de l'espace de travail et entre entités | 10 | `search`, `fetch`, contexte du compte, cinq lectures de l'espace de travail et les outils `upload-file` et `create-upload-url` |

Les familles d'outils ont des responsabilités différentes. Les relations des entreprises, des personnes et des opportunités passent par des champs à la création et à la mise à jour. Par exemple, une opportunité peut référencer une entreprise. Les relations des tâches et des notes sont associatives : une tâche peut concerner trois entreprises et deux personnes à la fois, d'où leurs propres endpoints de synchronisation. Nous n'avons pas ajouté Attach/Detach aux trois autres par souci d'uniformité. Il n'y a rien à quoi les rattacher.

[](#search-et-fetch-sont-un-contrat-pas-un-confort "Permalink")Search et fetch sont un contrat, pas un confort
--------------------------------------------------------------------------------------------------------------

`search` et `fetch` ne sont pas des outils génériques que nous aurions nommés ainsi par hasard. C'est exactement la paire qu'exige le connecteur Company Knowledge de ChatGPT : un client qui trouve des enregistrements par requête et les cite avec une URL stable. Les deux portent les attributs `#[Name('search')]` et `#[Name('fetch')]`, pour que le nom sur le réseau soit le bon quel que soit le nom de la classe. Les deux sont aussi déclarés en lecture seule, idempotents et en monde fermé dans leurs annotations d'outil MCP.

Nous avons mal conçu le contrat dès le premier essai. `search` publiait des URL comme `/app/{segment}/{id}`, sans le slug de l'espace de travail que le routage de Filament exige réellement, si bien que chaque URL de citation renvoyait une 404, y compris pour le propriétaire de l'enregistrement. `fetch` ne savait analyser que cette même forme erronée, il rejetait donc aussi la vraie URL qu'un utilisateur copie depuis la barre d'adresse de son navigateur. Les tâches et les notes n'avaient aucune page par enregistrement. Deux des cinq types d'entités interrogeables n'avaient donc d'emblée aucune URL à citer.

La correction a été `CanonicalRecordUrl`, une seule classe qui construit et analyse le format d'URL, utilisée par les deux outils. Répartir la construction et l'analyse sur deux fichiers, c'est la meilleure façon de les voir diverger. Un résultat de recherche qu'un client ne peut pas recoller dans fetch est pire qu'une absence de citation.

[](#les-descriptions-de-schéma-sont-des-prompts-pas-de-la-documentation "Permalink")Les descriptions de schéma sont des prompts, pas de la documentation
--------------------------------------------------------------------------------------------------------------------------------------------------------

Les schémas des outils de création et de mise à jour utilisent cette instruction pour `custom_fields` :

> « Valeurs des champs personnalisés sous forme de paires clé-valeur. IMPORTANT : vous DEVEZ d'abord lire la ressource crm-schema pour connaître les codes de champ valides pour ce type d'entité. Les codes de champ inconnus seront rejetés. Utilisez les codes de champ exacts du schéma (par exemple 'job\_title', et non 'jobTitle'). »

Ce n'est pas de la documentation d'API. Cette consigne s'adresse à un agent en pleine tâche et vise à prévenir deux erreurs que les modèles commettent réellement. La première consiste à deviner un code de champ plausible au lieu de le rechercher. La seconde consiste à écrire en camelCase une clé en snake\_case, parce que c'est la convention la plus courante dans les données d'entraînement. Les descriptions des outils font de même à un niveau plus général : « Créez une nouvelle entreprise dans le CRM. Utilisez la ressource crm-schema pour découvrir les champs personnalisés disponibles. » Elles renvoient le modèle à la ressource de schéma de chaque entité (`relaticle://schema/company`, un URI par entité) avant même qu'il appelle l'outil.

Cela ne fonctionne que parce que la ressource de schéma est peu coûteuse à lire et mise en cache par espace de travail pendant 60 secondes. Si la découverte exigeait un aller-retour de plus vers la base de données à chaque recherche de champ, nous serions tentés d'intégrer tout le schéma dans chaque description d'outil. Le coût en tokens se paierait alors à chaque appel, et non une seule fois par lecture de la ressource.

[](#des-descriptions-différentes-une-normalisation-partagée-des-champs-personnalisés "Permalink")Des descriptions différentes, une normalisation partagée des champs personnalisés
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Les champs personnalisés appartiennent à chaque espace de travail. Le `CustomFieldsSchemaDescriber` du chat présente les codes de champ et les libellés d'options dans le schéma de l'outil. Le `CustomFieldSchema` de MCP renvoie des définitions structurées contenant les libellés et les ID d'options.

Les deux surfaces d'écriture appellent `CustomFieldInput::normalize()` avant que `ValidCustomFields` valide le résultat. Les champs à choix acceptent des libellés d'options ou des ID. Les libellés ambigus échouent à la validation, donc un ID d'option résout les cas de libellés en double.

L'enum `CustomFieldType` porte les formats d'entrée et les exemples utilisés par les deux descriptions de schéma. Les valeurs de l'éditeur de texte enrichi acceptent le Markdown ou le HTML et sont enregistrées en HTML.

Cette frontière garde la présentation propre à chaque client et centralise la normalisation. Un nouveau champ n'a pas besoin d'un emplacement de schéma écrit à la main dans chaque outil.

[](#le-traitement-par-lots-relève-de-linterface-dapprobation-pas-du-protocole "Permalink")Le traitement par lots relève de l'interface d'approbation, pas du protocole
----------------------------------------------------------------------------------------------------------------------------------------------------------------------

Nos outils de suppression ont un aspect différent selon le client qui les appelle. C'est un choix de conception délibéré, pas une dérive. L'outil de suppression du chat accepte `ids: string[]`, soit un ou plusieurs ID. Son docstring le précise : « Passez un ID pour supprimer une seule entreprise, ou plusieurs pour toutes les supprimer en un seul appel. » Une demande avec plusieurs ID devient une seule `PendingAction` qu'un humain examine dans le cadre d'un plan, avec des décisions possibles élément par élément. Le modèle n'envoie donc pas trois appels de suppression distincts qui exigeraient chacun leur propre approbation.

Les outils de suppression de MCP prennent un seul `id` scalaire. Il n'y a pas d'étape d'approbation pour laquelle regrouper les appels : une écriture MCP s'exécute immédiatement dès que le jeton OAuth passe la vérification de sa capacité, donc rien n'équivaut à « réduire le nombre de cartes qu'un humain doit parcourir ». C'est une vraie lacune pour un agent qui fait un nettoyage en masse (supprimer douze opportunités obsolètes représente aujourd'hui douze appels). Nous ne pensons pas que ce soit évidemment le bon compromis. C'est simplement celui que nous avons fait en ne réexaminant pas le schéma une fois qu'il existait côté chat.

[](#les-permissions-du-jeton-et-lautorisation-de-lutilisateur-sont-deux-vérifications-distinctes "Permalink")Les permissions du jeton et l'autorisation de l'utilisateur sont deux vérifications distinctes
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Une écriture MCP doit répondre à deux questions distinctes avant de toucher la base de données : ce jeton autorise-t-il l'opération, et cet utilisateur peut-il modifier l'enregistrement. Ces deux vérifications s'appliquent volontairement à des endroits différents.

`ChecksTokenAbility` gère la première et doit traiter OAuth comme un cas particulier. Un jeton d'accès personnel Sanctum peut porter des capacités granulaires (`read`, `create`, `update`, `delete`), mais un jeton OAuth Passport, celui que détiennent réellement Claude ou ChatGPT, ne peut demander que `mcp:use`, parce que c'est le seul scope que [laravel/mcp](https://github.com/laravel/mcp) publie dans les métadonnées de son serveur d'autorisation. Les octrois par capacité ne sont pas exprimables avec OAuth. Détenir `mcp:use` autorise donc l'ensemble des outils. Le jeton lui-même définit séparément l'espace de travail dont ces outils peuvent consulter les données.

Cette liaison est assurée par `SetApiWorkspaceContext`. Les jetons OAuth portent un `workspace_id` faisant autorité, et le middleware ignore `X-Workspace-Id` pour ces jetons. Il définit le contexte du tenant et le guard web, puis applique `WorkspaceScope` aux modèles concernés. Sa méthode `terminate()` supprime ces scopes. Le middleware prend explicitement en charge FPM plutôt qu'Octane, parce que son état statique de modèles peut survivre à un nettoyage raté sous Octane.

Aucune de ces deux vérifications ne contrôle qu'une clé étrangère du corps de la requête appartient bien à l'espace de travail de l'appelant. C'est le rôle de `TenantFkValidator::assertOwned()`, appelé dans l'action elle-même. `CreateOpportunity` vérifie, avant l'insertion, que `company_id` et `contact_id` existent et appartiennent à l'espace de travail de l'appelant, indépendamment de ce que le middleware a déjà délimité. Un jeton avec `mcp:use` et une liaison d'espace de travail valide ne peut toujours pas pointer une nouvelle opportunité vers l'ID d'une entreprise qu'il aurait deviné à partir des données d'un autre tenant, car à ce niveau du chemin d'écriture rien ne se fie au seul scoping.

[](#les-annotations-doutil-servent-à-définir-les-règles-dutilisation-et-une-liste-tenue-à-la-main-finit-par-diverger "Permalink")Les annotations d'outil servent à définir les règles d'utilisation, et une liste tenue à la main finit par diverger
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Les [annotations d'outil](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool-annotations) de MCP (`readOnlyHint`, `idempotentHint`, `destructiveHint`, `openWorldHint`) ne sont pas de la décoration. Les contrôles de soumission aux annuaires de Claude et de ChatGPT les lisent, et un client peut raisonnablement s'appuyer sur `destructiveHint` pour décider s'il demande à l'utilisateur avant d'appeler un outil. Nous annotons chaque outil : les lectures sont marquées en lecture seule et idempotentes. Les mises à jour, les suppressions et les dissociations portent des indications destructives lorsque c'est pertinent. Les écritures de tâches qui envoient des notifications et les téléversements de fichiers déclarent un comportement en monde ouvert.

Nous avons pourtant publié une version comportant une lacune. La première version de notre test d'annotations vérifiait des attentes précises sur une liste de classes d'outils choisies à la main, et `WhoAmiTool` n'a jamais été ajouté à cette liste. Ainsi, 31 des 32 outils que nous avions alors déclaraient `openWorldHint`, le test restait vert et le 32e ne le déclarait pas, sans que personne le remarque. La correction n'a pas été une liste plus longue. Elle a consisté à examiner directement `RelaticleServer::$tools` par réflexion et à vérifier la propriété sur chaque classe réellement enregistrée. Ainsi, oublier d'ajouter un nouvel outil au jeu de données ne lui permet plus d'échapper au contrôle :

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

```

La même leçon, à savoir que la frontière est plus large qu'on ne le croit, est aussi apparue au niveau du transport. Quand `MCP_DOMAIN` est défini, le MCP server est monté à la racine d'un sous-domaine, qui est aussi son identifiant de ressource protégée OAuth. Les clients conformes à la RFC 9728 découvrent cet identifiant en faisant un `GET` sur l'URL nue et en traitant toute réponse 200 comme le document de métadonnées de la ressource protégée. Notre route racine y servait une bannière d'information en HTML. Un client basé sur rmcp (Codex, dans notre cas) a donc lu la bannière comme des métadonnées, n'y a trouvé aucun champ `resource` et a échoué avec un message assez opaque : « Protected resource metadata missing required resource field. » Claude et ChatGPT n'ont jamais rencontré ce problème, car leur SDK ne récupère que des chemins sous `/.well-known`, ce qui explique pourquoi il est passé inaperçu. La correction inverse le comportement par défaut : un GET nu reçoit désormais la bonne réponse du protocole, et la bannière ne s'affiche que pour une vraie navigation de niveau supérieur du navigateur, détectée avec `Sec-Fetch-Mode: navigate`, un signal de navigation du navigateur. Les clients qui ne sont pas des navigateurs peuvent aussi envoyer cet en-tête, ce n'est donc pas un contrôle d'authentification.

[](#ce-que-nous-ferions-autrement "Permalink")Ce que nous ferions autrement
---------------------------------------------------------------------------

Nous avons d'abord maintenu des chemins de traduction des champs personnalisés distincts. L'implémentation actuelle partage la normalisation via `CustomFieldInput` et les descriptions de format via `CustomFieldType`. Cela réduit les dérives tout en laissant le chat mettre en avant les libellés et MCP exposer des définitions structurées. La parité des schémas mérite encore des tests chaque fois que les formats de valeur pris en charge changent.

Nous reverrions aussi dès maintenant le traitement par lots des suppressions MCP, au lieu d'en faire une asymétrie que nous n'avons remarquée qu'en rédigeant cet article. Il était juste de livrer d'abord les suppressions d'un seul enregistrement et de bien concevoir l'approbation par lots côté chat, où le coût d'expérience utilisateur de l'absence de lots était immédiat et visible. Mais un agent qui nettoie un CRM en masse est un vrai cas d'usage de MCP, et il le paie aujourd'hui en nombre d'appels, sans le moindre gain de sécurité. La vérification du scope OAuth n'est pas plus rigoureuse parce qu'on la fait douze fois au lieu d'une.

Si vous construisez un MCP server au-dessus de données de production, voici l'approche qui a le mieux fonctionné pour nous. Faites passer chaque écriture par les mêmes classes d'action que votre application web utilise déjà. L'outil MCP forme alors une fine couche de traduction : schéma en entrée, appel validé de l'action, ressource en sortie. Tout le reste, c'est-à-dire les annotations, la découverte des champs personnalisés et les URL canoniques, n'est que de la décoration propre au protocole posée sur ce même noyau. La liste complète des outils et les instructions de configuration se trouvent sur [/developers/mcp](https://relaticle.com/fr/developers/mcp). Pour la vue côté utilisateur du même serveur, consultez [connecter Claude à votre CRM avec MCP](https://relaticle.com/fr/blog/connecter-claude-a-votre-crm-avec-mcp) et [ce que signifie vraiment un CRM agent-native](https://relaticle.com/fr/blog/ce-que-signifie-vraiment-un-crm-agent-native).

 Tags [ #mcp ](https://relaticle.com/fr/blog/tag/mcp) 

 Sur cette page

 Continuer la lecture

 Articles associés. 
--------------------

- [  2 nov. 2026  Ingénierie 

    ###  Un essai gratuit de modèles IA premium détourné : ce que nous avons changé 

    Un essai sans carte qui débloquait des modèles IA premium a attiré des comptes qui n'ont jamais touché au CRM. Au lieu d'exiger une carte, nous lions les modèles premium au premier vrai enregistrement.

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

     ](https://relaticle.com/fr/blog/essai-gratuit-des-modeles-ia-premium-detourne-ce-que-nous-avons-change)
- [  21 oct. 2026  Ingénierie 

    ###  php2shell : comment nous avons corrigé Relaticle, et comment corriger le vôtre 

    php2shell désigne deux failles critiques de PHP qui permettent à un attaquant d'exécuter du code sur un serveur web. Ce que nous avons corrigé sur Relaticle Cloud, et ce qu'une installation auto-hébergée doit faire aujourd'hui.

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

     ](https://relaticle.com/fr/blog/php2shell-corriger-php-dans-docker-et-forge)
- [  22 sept. 2026  Ingénierie 

    ###  Des champs personnalisés qui fonctionnent partout, sans code par champ 

    Comment Relaticle rend les champs personnalisés disponibles dans les formulaires, les API, le chat et MCP, avec une normalisation commune, une sémantique claire des valeurs vides et des limites explicites.

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

     ](https://relaticle.com/fr/blog/champs-personnalises-qui-fonctionnent-partout)
