Mankomail

Serveur MCP ​

Le Model Context Protocol (MCP) permet à un assistant d’IA d’appeler des outils proposés par une autre application. Chaque instance de Mankomail expose un serveur MCP : Claude Desktop, Claude Code, Cursor ou tout autre client MCP peut s’y connecter et travailler sur vos workflows et vos boîtes, avec vos droits et rien de plus.

Le serveur publie la couche de tools de l’instance, les mêmes outils typés que l’analyseur et l’assistant de workflows emploient en interne. Ce qu’un assistant voit par MCP est exactement ce avec quoi Mankomail travaille lui-même.

Ce qu’un assistant peut faire ​

Chaque tool est une capacité de l’instance, avec un nom, une description, une entrée typée et une sortie typée. Les tools sont groupés par domaine :

  • Catalogue et documentation : lister les nœuds que vous pouvez employer, décrire un nœud en entier (paramètres, ports de sortie, données produites, connexions requises), chercher et lire cette documentation.
  • Workflows : lister vos workflows, en lire un en entier avec sa validation et son historique, valider ou compiler une proposition, proposer un nouveau workflow ou des modifications d’un workflow existant, exécuter le brouillon sur un vrai mail en essai, puis créer un brouillon, modifier un brouillon et publier.
  • Exécutions : lister les exécutions récentes, en lire une étape par étape pour voir ce que chaque nœud a produit et où il a échoué.
  • Boîtes : lister vos boîtes, obtenir leurs statistiques, regrouper les mails récents en flux, chercher par expéditeur ou par objet (en-têtes et aperçus, jamais un corps complet), lister ce qu’aucun workflow n’a traité, et simuler quels mails vos workflows publiés auraient pris.
  • Connexions : quelles connexions les nœuds peuvent exiger, et si chacune est configurée pour vous.
  • Tables : lister les Tables avec leurs colonnes, et en créer une.

La liste complète, avec entrées et sorties, se trouve dans la référence des tools.

Le modèle de confiance ​

Un client MCP s’authentifie avec une clé d’API, créée dans Réglages › Clés d’API. Une clé agit au nom du membre qui l’a créée, avec son rôle, ses boîtes et son périmètre, et elle est encore limitée par les portées choisies à sa création. Une portée n’ajoute jamais un droit : elle en retire.

  • Lecture et écriture sont séparées. Chaque tool est soit un tool de lecture, soit un tool d’écriture. Un tool de lecture exige la portée read de son domaine, un tool d’écriture la portée write. Les quatre tools d’écriture sont workflow_create_draft, workflow_update_draft, workflow_publish et tables_create.
  • Rien n’est publié sans workflows:write. Une clé workflows:read laisse un assistant explorer, proposer et compiler (essayer exige executions:write), mais chaque proposition reste une valeur dans la conversation : c’est le membre qui crée le brouillon ou publie, dans l’éditeur ou avec une clé qui porte workflows:write.
  • L’assistant ne voit que ce qu’il peut appeler. tools/list ne renvoie que les tools autorisés par les portées de la clé ; l’appel de tout autre tool est refusé avec une erreur nommée. Voir Portées et tools.
  • Aucun secret n’est jamais exposé. connections_list dit si une connexion est configurée et nomme les identifiants utilisables ; il ne renvoie jamais un jeton, un mot de passe ni une clé d’API. Les corps de mails ne sont jamais renvoyés non plus : les tools de boîte travaillent sur les en-têtes et des aperçus bornés.
  • Une table n’est créée que par un administrateur, comme dans l’interface : la clé d’un membre ordinaire ne peut pas en créer, même avec tables:write.

Un essai exige executions:write, comme la route REST qui en lance un. Il n’envoie ni n’écrit rien hors de l’instance, mais les nœuds d’IA appellent bien leur modèle (ce qui coûte), et l’essai est enregistré comme une exécution simulée.

Le point de terminaison ​

Le serveur répond sur POST <PUBLIC_BASE_URL>/api/v1/mcp avec le transport Streamable HTTP de la spécification MCP courante. Envoyez la clé dans l’en-tête Authorization :

http
POST /api/v1/mcp HTTP/1.1
Authorization: Bearer mk_…
Content-Type: application/json
Accept: application/json, text/event-stream

Le transport est sans état : chaque requête porte sa clé, construit le serveur pour le membre de cette clé, et rien ne survit entre deux appels. Le serveur n’attribue aucun identifiant de session, il n’y a donc pas d’en-tête Mcp-Session-Id à renvoyer, et une clé révoquée est refusée dès la requête suivante. Conséquences :

  • GET et DELETE sur le point de terminaison renvoient 405 Method Not Allowed : il n’y a ni flux à l’initiative du serveur ni session à clore. Aucun tool n’en a besoin.
  • Les réponses sont du JSON simple quand le client n’exige pas un flux SSE, ce qui garde curl et les clients minimaux simples.
  • Plusieurs répliques du serveur servent le même client sans se concerter.

Une session de navigateur authentifie aussi le point de terminaison : un membre connecté atteint tous les tools que son rôle permet. Le serveur MCP est distinct de l’API REST, qui expose les mêmes ressources sous forme de routes HTTP ; les deux acceptent les mêmes clés, voir Authentification.

Pour continuer ​