Le serveur MCP

Chaque espace MADATA embarque un serveur Model Context Protocol à son adresse /mia/mcp. Un assistant IA, ou n’importe quel programme, s’y connecte et appelle les outils métier de l’espace.

01Qu’est-ce que c’est

Le serveur MCP est la seconde façade sur le moteur d’outils de Mia, l’assistant intégré. Là où Mia mène sa boucle en interne, le serveur MCP publie exactement les mêmes outils à un client externe : Claude, ChatGPT, Gemini, Mistral Le Chat, ou votre code.

Le client reçoit un catalogue d’outils (tools/list), les appelle (tools/call), et lit des ressources en lecture seule. Toute l’exécution se fait avec les droits de l’utilisateur propriétaire de la clé.

02Endpoint & transport

URL: https://<espace>.madata.app/mia/mcp
Méthode: POST : corps JSON-RPC 2.0
Auth: En-tête Authorization: Bearer mia_… (ou OAuth 2.1)
Content-Type: application/json

Le transport est du HTTP simple, compatible avec les clients « Streamable HTTP » modernes. Il n’y a pas de flux SSE serveur → client :

Méthode HTTP	Réponse	Rôle
`POST`	`200` + corps JSON-RPC	Canal principal : toutes les méthodes du protocole.
`GET`	`405`	Ouvrirait un flux de notifications ; le serveur n’en a pas.
`DELETE`	`204`	Fin de session ; serveur sans état, sans effet.
`OPTIONS`	`204` + CORS	Préflight (extensions, clients web). `Access-Control-Allow-Origin: *`.

03Poignée de main (initialize)

Premier appel de toute session. Le serveur négocie la version du protocole : il renvoie celle demandée si elle fait partie des versions supportées (2025-06-18, 2025-03-26, 2024-11-05), sinon la plus récente.

jsonrequête → réponse initialize

{"jsonrpc":"2.0","id":1,"method":"initialize",
 "params":{"protocolVersion":"2025-06-18","capabilities":{},
           "clientInfo":{"name":"mon-app","version":"1.0"}}}

{"jsonrpc":"2.0","id":1,"result":{
  "protocolVersion":"2025-06-18",
  "capabilities":{"tools":{},"resources":{},"prompts":{}},
  "serverInfo":{"name":"madata-mia","version":"1.1.0","title":"Madata",
                "websiteUrl":"https://<espace>.madata.app"},
  "instructions":"Cette plateforme de gestion s'appelle Madata. Agis via tes outils…"
}}

Le champ instructions rappelle au client de désigner la plateforme par « MADATA » et d’agir via les outils plutôt que de renvoyer l’utilisateur vers l’interface.

04Méthodes du protocole

Méthode	Rôle
`initialize`	Négociation de version, capacités, serverInfo.
`notifications/initialized`	Accusé de réception (le serveur répond vide).
`tools/list`	Catalogue d’outils, filtré par la portée de la clé.
`tools/call`	Exécute un outil.
`resources/list` · `resources/read`	4 ressources en lecture seule (voir Ressources).
`resources/templates/list`	Renvoie une liste vide (pas de templates d’URI).
`prompts/list` · `prompts/get`	8 prompts prêts à l’emploi.
`ping`	Renvoie `{}`.

Toute autre méthode (logging/setLevel, completion/complete, roots/list…) renvoie l’erreur JSON-RPC -32601 « méthode inconnue » en HTTP 200 : c’est une réponse normale de découverte, pas une panne.

05Appeler un outil (tools/call)

jsontools/call

{"jsonrpc":"2.0","id":2,"method":"tools/call",
 "params":{"name":"get_kpi","arguments":{"period":"month"}}}

{"jsonrpc":"2.0","id":2,"result":{
  "content":[{"type":"text","text":"{ \"ca_ttc\": 4210000, … }"}],
  "isError":false
}}

Le résultat arrive dans content (blocs text, ou resource pour un fichier généré). Les outils d’écriture reçoivent un paramètre company_name injecté automatiquement pour les espaces multi-société.

Résultats « souples »

Quand un appel aboutit mais que la réponse est « introuvable », « argument à corriger », « cible vide » ou « accès refusé », isError reste false : la réponse porte une information exploitable (contacts proches, nom de champ à corriger). Le client s’en sert au lieu de rejouer le même appel à l’identique.

06Codes d’erreur & contrat de statut

La distinction est cruciale pour un connecteur IA : un 401 lui fait jeter sa clé et relancer un consentement OAuth ; un 403 le laisse connecté et il réessaie.

Situation	HTTP	JSON-RPC	En-têtes
Clé absente / invalide / expirée / révoquée	`401`	`-32001`	`WWW-Authenticate: Bearer resource_metadata="…"`
Mia désactivée sur l’espace	`403`	`-32001`	`Retry-After: 300`
Abonnement Mia inactif	`403`	`-32001`	`Retry-After: 300`
Ressource facturée touchée	`403`	`-32003`	Message métier : « à gérer dans le portail ».
Limite de débit dépassée	`429`	`-32029`	`Retry-After: 60`
Méthode de protocole inconnue	`200`	`-32601`	Découverte normale.
Erreur d’exécution d’un outil	`200`	résultat `isError:true`
Panne interne	`500`	`-32603`
JSON illisible / espace introuvable	`400`	`-32700` / `-32600`

07Limite de débit

120 requêtes / minute par utilisateur, en fenêtre glissante. Les méthodes de poignée de main et de catalogue (initialize, tools/list, prompts/list, resources/list, ping…) ne comptent pas : seuls les appels d’outils sont plafonnés. Dépassement → 429 + Retry-After: 60.

08Portée & droits

Trois niveaux se combinent :

Portée de la clé : read_only (lecture seule), full_access (lecture + écriture) ou custom (liste blanche d’outils).
Mode d’accès de l’utilisateur, réglé dans le portail (« Lecture seule » ou « Lecture et écriture ») : un utilisateur en « Lecture seule » n’écrira jamais, quelle que soit la portée de la clé.
Droits de l’utilisateur dans l’espace : un outil pour lequel l’utilisateur n’a pas les droits n’apparaît pas dans tools/list.

Invariant

Quelle que soit la portée, une clé ne peut jamais créer ni modifier les ressources facturées : utilisateurs, sociétés, points de vente, applications. Toute tentative renvoie -32003. Inutile de demander à élever les droits : le refus ne vient pas de là.

09Disponibilité

L’accès MCP nécessite un abonnement Mia actif sur l’espace. Si l’abonnement est inactif, le serveur répond 403 + Retry-After : la connexion reste en place et le client réessaie.