Mankomail

Portées et tools ​

Une clé d’API porte des portées de la forme <domaine>:<verbe>, avec read, write ou * pour verbe, et write couvre read. La grammaire et la liste complète des domaines sont dans Portées de l’API. Cette page dit comment le serveur MCP les lit.

Une portée n’accorde jamais plus que le membre à qui la clé appartient : la clé d’un membre ordinaire portant tables:write ne peut toujours pas créer de table, parce que ce membre ne le peut pas.

Le domaine de chaque tool ​

Le serveur déduit la portée exigée du nom et de l’effet du tool : le préfixe du nom interne donne le domaine, l’effet donne le verbe.

Préfixe du toolDomaineTools
catalog., docs., workflow.workflowscatalog_describe, catalog_node, docs_search, docs_read, workflow_list, workflow_read, workflow_describe, workflow_validate, workflow_compile, workflow_propose_new, workflow_propose_changes (lecture) ; workflow_create_draft, workflow_update_draft, workflow_publish (écriture)
execution.executionsexecution_list, execution_read (lecture)
workflow.test_run (exception)executionsworkflow_test_run (écriture)
mailbox., journal., coverage.mailboxesmailbox_list, mailbox_stats, mailbox_cluster, mailbox_search, journal_unmatched, coverage_simulate (lecture)
connections.connectionsconnections_list (lecture)
tables.tablestables_list (lecture) ; tables_create (écriture)

Un tool de lecture exige <domaine>:read ; un tool d’écriture exige <domaine>:write. Une exception : workflow_test_run n’écrit rien à l’extérieur, mais il crée une exécution et fait appeler leur modèle aux nœuds d’IA, ce qui coûte. Il exige executions:write, la portée de la route REST équivalente POST /workflows/{id}/test : une clé en lecture seule ne peut pas dépenser. Une clé satisfait une exigence quand elle porte la portée exacte, la portée write du domaine pour une exigence read, ou le * du domaine. Les autres domaines de l’API (messages, contacts, admin…) n’ont aucun tool MCP aujourd’hui.

La description de chaque tool dans tools/list se termine par la portée qu’il exige, par exemple « Requires scope workflows:write. », pour qu’un assistant puisse vous expliquer un refus.

Le filtrage de tools/list ​

tools/list ne renvoie que les tools que la clé peut appeler. Une clé workflows:read liste les onze tools de lecture du domaine workflows et rien d’autre : pas de workflow_publish, pas de mailbox_list. Annoncer un tool qu’on refuserait ensuite ferait tourner l’assistant en rond.

Par une session de navigateur plutôt qu’une clé, le membre a toutes les portées que son rôle permet, et la liste complète apparaît.

La forme d’un refus ​

Un client peut appeler un tool sans l’avoir listé, donc tools/call revérifie la portée. Un refus n’est pas une erreur de protocole : c’est un résultat de tool avec isError: true, pour que l’assistant le lise et réagisse.

json
{
  "isError": true,
  "content": [
    { "type": "text", "text": "{\"error\":{\"code\":\"api_key.scope_missing\",\"message\":\"this key lacks the scope workflows:write required by workflow.publish\"}}" }
  ],
  "structuredContent": {
    "error": {
      "code": "api_key.scope_missing",
      "message": "this key lacks the scope workflows:write required by workflow.publish"
    }
  }
}

La même forme porte les autres refus. code est stable et destiné aux programmes :

CodeSignification
api_key.scope_missingla clé n’a pas la portée qu’exige le tool
tool.not_foundaucun tool ne porte ce nom
tool.invalid_inputles arguments ne respectent pas l’inputSchema du tool (champ inconnu, mauvais type, borne dépassée)
tool.resource_not_foundle workflow, la boîte, l’exécution, le type de nœud ou la page n’existe pas ou appartient à un autre membre
workflow.archived, workflow.invalid_graph et les autres codes workflow.…un refus métier : un workflow archivé ne se modifie pas, un graphe enregistré est illisible, un brouillon invalide ne peut pas être essayé

Deux issues ne sont pas des refus : workflow_publish qui répond ok: false avec les erreurs bloquantes, et workflow_propose_changes qui répond ok: false avec une opération rejetée. Ce sont des résultats normaux, qui décrivent ce qu’il faut corriger.

Sans clé valide, la requête n’atteint jamais MCP : le point de terminaison répond 401 avec auth.unauthenticated dans le format d’erreur de l’API. Une clé expirée ou révoquée reçoit la même réponse.

Exemples de clés ​

Un analyste en lecture seule. Un assistant qui explique une boîte, propose des automatisations et diagnostique les exécutions échouées, sans jamais rien changer :

text
workflows:read   executions:read   mailboxes:read   connections:read   tables:read

Il peut décrire le catalogue, lire tous les workflows, compiler et proposer, lire les exécutions, chercher et regrouper les mails, et voir quelles connexions et quelles tables existent. Il ne peut ni lancer un essai (il faut executions:write), ni créer, modifier ou publier un workflow, ni créer une table.

Un constructeur. Un assistant qui construit des workflows de bout en bout, publication comprise :

text
workflows:write   executions:write   mailboxes:read   connections:read   tables:read

workflows:write couvre les tools de lecture du domaine : lire, proposer, créer le brouillon, le modifier, le publier. executions:write ajoute les essais sur de vrais mails. Gardez tables:read, sauf si le membre est un administrateur qui veut que l’assistant crée des tables : donnez alors tables:write.

Une clé pour une seule tâche. Les portées sont par domaine, donc une clé peut être plus étroite encore : mailboxes:read seul pour un assistant qui ne fait que rendre compte des boîtes, ou workflows:read et executions:read pour un assistant qui n’enquête que sur les exécutions échouées.

Donnez une date d’expiration à une clé à sa création si elle sert une tâche ponctuelle, et révoquez-la ensuite : l’appel suivant est refusé.

Pages liées ​