MCP Scopes

Les scopes sont les permissions fines des jetons MCP. Chaque outil déclare les scopes qu'il exige ; un jeton n'a accès qu'aux outils dont il possède tous les scopes. C'est l'équivalent d'un « scope » OAuth, pensé pour borner le rayon d'action d'un agent LLM.

Concept

Trackily expose 43 scopes, en paires :read / :write par domaine, sauf quatre domaines en lecture seule (stats:read, reports:read, checkouts:read, analytics:read) et ai:generate, qui n'a pas de paire.

Le contrat :

• Un outil déclare ses scopes dans son registerTool (scopes: [S.CAMPAIGNS_WRITE]).
• tools/list ne rend à un jeton que les outils dont il a tous les scopes (même règle pour resources/list et prompts/list). Un outil absent de la liste d'un agent est un scope manquant, pas un outil manquant.
• À l'appel, le serveur vérifie que tous les scopes requis sont dans le jeton. Sinon : erreur JSON-RPC -32002, message Missing scope for <outil>, et error.data.required porte la liste des scopes que l'outil exige — tous, pas seulement ceux qui manquent. L'appel refusé entre au journal d'audit comme un appel d'outil en erreur (event_type tool, result_status error).
• Un outil qui exige plusieurs scopes les exige tous : bind_landing_to_email_list demande email:write et landings:write.

La vérification se fait dans autopilot.js, fonction hasScope() :

function hasScope(tokenRow, required) {
  if (!Array.isArray(required) || !required.length) return true;
  const granted = Array.isArray(tokenRow?.scopes) ? tokenRow.scopes : [];
  return required.every(s => granted.includes(s));
}

La liste complète

Tracker d'affiliation

E-commerce

E-mail

WhatsApp

Le canal WhatsApp a sa propre paire, jamais celle de l'e-mail : sur un compte de l'API officielle, chaque message est facturé par le fournisseur et engage la note de qualité du numéro ; sur la voie « web » (une SIM par WhatsApp Web), rien n'est facturé, mais chaque envoi engage la SIM elle-même, et un numéro banni est perdu. Un jeton taillé pour l'e-mail ne doit pas hériter du droit d'envoyer sur ce canal.

Aucun scope, pas même whatsapp:write, ne permet de créer un compte WhatsApp, d'en changer les identifiants ou de démarrer un appairage : aucun outil ne le fait. Cf. Tools Reference — whatsapp-tools.

Les 4 presets

Pour éviter de cocher 43 cases, l'écran de création d'un jeton propose des presets (MCP Autopilot → onglet Tokens → + New token → Scope preset). Ils sont définis dans autopilot.js, SCOPE_PRESETS.

read_only

23 scopes : tous les :read, aucune écriture. Ni ai:generate, ni aucun :write. Pour un agent de lecture : résumé de la semaine, surveillance, tableau de bord.

operator

40 scopes : toutes les lectures et les écritures du quotidien, sauf trois — settings:write, networks:write et ai:generate.

Ce que ça veut dire en pratique : un jeton operator pilote campagnes, landings, funnels, boutiques, commandes, e-mail et WhatsApp, mais il ne peut ni appeler les outils qui exigent ai:generate (générer une landing, translate_landing, audit de conformité — même en mode rules —, description ou traduction de produit), ni écrire un réglage (domaines, zones de livraison, workflows de cloaking, relais SMTP, état d'un compte de paiement). Attention : translate_landing_html, duplicate_funnel_for_language et propose_funnel appellent un LLM sans exiger ai:generate — un jeton operator peut donc les lancer.

full

42 scopes : tous, sauf settings:write. C'est operator plus ai:generate et networks:write.

admin

43 scopes, tous, settings:write compris. À réserver à un seul jeton « bris de glace » pour la maintenance ponctuelle, gardé en coffre.

Tableau de correspondance preset → scopes

Composition multi-scope

Quelques outils demandent plusieurs scopes. Exemples (la colonne Scopes de la Tools Reference les donne tous) :

Si le jeton n'a qu'une partie des scopes requis, l'appel est refusé comme décrit plus haut, et error.data.required rend la liste complète exigée par l'outil.

Choisir un preset

Tu veux qu'un agent fasse...

  ... du reporting, de la surveillance uniquement
      → read_only

  ... le quotidien : pauses, budgets, landings écrites à la main, funnels,
      boutiques, commandes, e-mail, WhatsApp
      → operator

  ... le quotidien + la génération par IA (landings, traductions,
      audit de conformité — compliance_check, dans ses deux modes,
      même rules —, descriptions de produits)
      → full   (ou un jeton custom : operator + ai:generate)

  ... écrire des réglages : domaines, zones de livraison, workflows de
      cloaking, relais SMTP, état des comptes de paiement
      → admin  (réservé à ce jeton-là, jamais partagé)

Custom (cocher à la main)

L'option Custom — pick scopes manually du même menu permet de cocher les scopes un par un plutôt que d'appliquer un preset. Utile pour :

• Un agent dédié au commerce Shopify : stores:read, products:read/write, orders:read/write, customers:read/write, analytics:read, inventory:read/write, discounts:read/write, collections:read/write, content:read/write.
• Un agent dédié à l'e-mail : email:read, email:write, et landings:write s'il doit brancher une landing sur une liste (bind_landing_to_email_list). Les déclencheurs postback → e-mail n'exigent que email:write.
• Un agent dédié à WhatsApp : whatsapp:read et whatsapp:write. En lecture seule, whatsapp:read suffit pour consulter journal, suppression et règles, et pour simuler un routage (simulate_whatsapp_routing n'écrit rien).
• Un agent de reporting financier : stats:read, analytics:read, reports:read, orders:read, customers:read.

Un jeton au scope minimal est plus sûr : moins de surface si le jeton fuite, moins de dégâts si le LLM se trompe.

Évolutions

Un jeton garde les scopes qu'il avait à sa création : le serveur les enregistre sur le jeton, et ne recalcule rien depuis les presets. Quand un domaine arrive — whatsapp:read et whatsapp:write en sont l'exemple —, les presets l'incluent pour les nouveaux jetons, mais un jeton operator créé avant ne voit toujours aucun outil WhatsApp.

Pour lui donner le nouveau domaine :

• crée un nouveau jeton avec le preset voulu, puis révoque l'ancien ;
• ou modifie ses scopes par l'API d'administration, PUT /admin/api/autopilot/tokens/:id avec un tableau scopes complet (l'écran des jetons ne propose pas d'édition des scopes).

La rotation (l'icône « Rotate » de la liste des jetons) ne suffit pas : elle recopie les scopes de l'ancien jeton sur le nouveau.

Retirer ou renommer un scope retirerait des droits aux jetons existants sans qu'ils le sachent : un scope inconnu est écarté à la création du jeton, et à l'appel le serveur compare des chaînes exactes.

Erreurs courantes

• Missing scope for X avec un jeton operator — l'outil exige sans doute ai:generate ou settings:write, les deux scopes utiles qu'operator n'a pas. La colonne Scopes de la Tools Reference le dit. Passe par un jeton full (pour l'IA), admin (pour les réglages), ou un jeton custom.
• L'agent ne voit aucun outil WhatsApp — le jeton date d'avant whatsapp:read / whatsapp:write (voir la section Évolutions ci-dessus), ou il a été créé en custom sans eux.
• L'agent lit mais n'écrit pas — jeton read_only au lieu d'operator. Recrée-le avec le bon preset.
• Un outil qui marche en local mais pas en production — le jeton de production n'a pas le même jeu de scopes. Compare les deux jetons.
• Le journal d'audit se remplit d'erreurs « Missing scope for … » — l'agent tente des outils hors de son jeton. Restreins ses instructions, ou élargis ses scopes.

Voir aussi

• Tokens — créer un jeton avec un jeu de scopes
• Tier System — l'autre couche de défense, pour les actions destructrices
• Tools Reference — le scope requis de chaque outil