MCP (Model Context Protocol)#

Trame expose un serveur MCP sur POST /mcp (JSON-RPC 2.0, protocolVersion: 2025-06-18) permettant à un agent IA d'agir sur un tenant avec exactement les mêmes scopes qu'une clé API classique — jamais plus. L'authentification est la même clé X-Api-Key que le reste de l'API REST.

Comme pour les routes REST, le chemin se concatène à la base de l'API : l'URL complète est donc https://<base-api>/public/mcp (voir Vue d'ensemble).

Méthodes JSON-RPC#

initialize — renvoie la version de protocole et les capacités du serveur.
tools/list — renvoie la liste des outils disponibles (nom, description, schéma d'entrée).
tools/call — exécute un outil ({ "name": "...", "arguments": {...} }).

bash

curl -X POST "https://<base-api>/public/mcp" \
  -H "X-Api-Key: <votre-clé>" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

bash

curl -X POST "https://<base-api>/public/mcp" \
  -H "X-Api-Key: <votre-clé>" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"trame_search","arguments":{"query":"facture","mailbox":"contact@exemple.com"}}}'

Les 10 outils réels et leur scope#

Les routes de la colonne de droite sont données comme le reste de la documentation : relatives à la base de l'API, segment de montage compris.

Outil	Scope requis	Opération / route équivalente	Arguments obligatoires
`trame_search`	`read:conversations`	`GET /v1/search`	`query`, `mailbox`
`trame_conversation_get`	`read:conversations`	`GET /v1/conversations/:id`	`id`, `mailbox`
`trame_draft_create`	`drafts:write`	`POST /v1/drafts`	—
`trame_draft_update`	`drafts:write`	`PATCH /v1/drafts/:id`	`id`, `mailbox`
`trame_contact_get`	`read:contacts`	`GET /v1/contacts/:id`	`id`, `mailbox`
`trame_contact_create`	`write:contacts`	`POST /v1/contacts`	—
`trame_calendar_list`	`read:calendar`	`GET /v1/calendars`	—
`trame_calendar_event_create`	`write:calendar`	`POST /v1/calendar-events`	—
`trame_task_get`	`read:tasks`	`GET /v1/tasks/:id`	`id`, `mailbox`
`trame_task_create`	`write:tasks`	`POST /v1/tasks`	—

Le schéma d'entrée exact de chaque outil est rendu par tools/list — c'est la référence à consommer côté agent. Les outils de création acceptent un objet libre : les champs attendus sont ceux de la route REST équivalente, décrits dans Endpoints REST (par exemple bookId + displayName pour un contact, calendarId + title + startMs/endMs pour un événement).

Aucun outil send n'existe et ne peut exister par construction (voir garde-fous ci-dessous).

Garde-fous#

Garde structurelle anti-envoi — le manifeste d'outils est validé au démarrage du serveur : tout nom, opération ou route d'outil contenant un effet d'envoi de mail fait échouer la validation. Ce n'est pas une règle documentaire qu'on pourrait oublier de respecter en ajoutant un outil — c'est une garde qui casse le serveur si on essaie.
Approbation agent — une clé kind: 'agent' avec approval: 'required' ne s'exécute jamais directement pour un outil d'écriture : l'appel passe par une file d'approbation humaine avant tout effet. /mcp gère ses propres approbations en interne (contrairement au reste de l'API REST, où le gate d'approbation est appliqué avant le dispatch) : la route elle-même ne renvoie donc jamais le 202 documenté pour les routes REST — le résultat de l'approbation est porté par la réponse JSON-RPC.
Un seul dispatcheur de scope — scopeForMcpTool(name) fait correspondre chaque outil à exactement le même scope que sa route REST équivalente : pas de double définition qui pourrait diverger.
Audit — chaque appel d'outil (succès, refus, erreur, approbation en attente) est audité avec le vrai scope de l'outil et l'identité de la clé appelante.

Erreurs JSON-RPC#

Les erreurs suivent le format JSON-RPC standard : { "jsonrpc": "2.0", "id", "error": { "code", "message" } }. Codes utilisés : -32600 (requête invalide), -32601 (méthode inconnue), -32602 (paramètres/outil invalides), -32001 (non autorisé — clé/scope), -32603 (erreur interne).

Le service MCP peut être indisponible sur un espace : la requête répond alors 503 au niveau HTTP (et non une erreur JSON-RPC).

Statut : pas encore d'exemple de session MCP complète multi-appels dans cette page (lot A4).