Limiter un jeton MCP Carbon Forge à un seul agent

Aussi en: English, Español, Português, 日本語, Deutsch, 한국어, 简体中文, Italiano, हिन्दी · Tous les guides en français

Transparence : nous développons Carbon Forge chez 100monkeys.ai, lisez donc ceci comme le récit du fabricant. Ce guide a été rédigé par l'un de nos agents d'IA à partir de la documentation publique (en anglais), surtout MCP token scopes (R#62460), MCP tokens (R#61824) et la page Tokens du catalogue (R#62188), puis relu par l'entreprise ; cette version française est une traduction du guide original en anglais. Les noms de presets, les arguments et les phrases citées viennent de la documentation ; elle ne donne aucun appel de création complet, d'où la liste des arguments plutôt qu'un exemple. Les citations restent en anglais, avec leur traduction à côté. Là où la documentation laisse une question ouverte, la dernière section le dit.

Deux limites sur chaque jeton

Un jeton porte un plafond de rôle (viewer, editor ou admin) et un périmètre d'outils, "the explicit set of MCP tools the bearer is allowed to call." (l'ensemble explicite des outils MCP que le porteur a le droit d'appeler.) Le plafond de rôle borne la permission ; le périmètre la restreint encore. L'exemple de la documentation : un périmètre SCM reader sur un jeton admin renvoie le même catalogue d'outils que le même périmètre sur un jeton viewer.

Étape 1. Décider ce que l'agent doit faire

Écrivez le travail de l'agent en une ligne avant d'ouvrir le formulaire : retrouver et raisonner, tenir des notes, lire du code, construire sur une lane, ou publier une version. Chacun correspond à un preset ci-dessous. La règle de la documentation : "Default to the narrowest preset that still covers what the client needs." (Par défaut, prenez le preset le plus étroit qui couvre encore les besoins du client.)

Étape 2. Fixer le plafond de rôle

Ouvrez les réglages, choisissez API tokens, puis le workspace et un plafond de rôle. Les presets SCM nomment le rôle qui leur va : SCM reader avec viewer, SCM agent et SCM release avec editor.

Étape 3. Choisir le preset le plus étroit

Les presets, avec le nombre d'outils donné par la documentation (chacun inclut cortex.ground) :

• Read-only memory (read_only_memory, 14) : lire les pages et les atomes, chercher, suivre les liens croisés ; aucune écriture.
• Basic LLM memory (basic_memory, 30) : lire et écrire les pages, les atomes et les tags, et chercher.
• Knowledge-graph reader (knowledge_graph_reader, 31) : toutes les surfaces de contenu et le graphe, aucune écriture.
• SCM reader (scm_reader, 58) : arbres de code, lanes, changesets, cuts et arborescence de fichiers, avec les pages et la recherche ; aucune écriture.
• SCM agent (scm_agent, 104) : les lectures SCM, plus l'écriture de pages, d'atomes, de lanes et d'arbres, l'intégration des lanes, les cuts et le rendu.
• SCM release (scm_release, 67) : les lectures SCM, plus l'intégration et l'approbation des lanes, les cuts, l'envoi d'archives et la publication d'un site.
• Full access (full, 177) : tous les outils, dans la limite du plafond de rôle.

Un agent de code qui construit sur une lane reçoit SCM agent ; le relecteur qui approuve, SCM release ; un agent de recherche, un reader. La documentation réserve Full access à un client "trusted with anything the role can do" (à qui l'on confie tout ce que le rôle permet).

Étape 4. Utiliser Custom pour un outil de plus

Quand il manque un outil à un preset, choisissez Custom et prenez les outils dans le sélecteur groupé. L'exemple de la documentation est un agent de publication "that should be able to create comments but not pages" (qui doit pouvoir créer des commentaires mais pas des pages). Le périmètre s'applique à la liste d'outils, au manifeste à /api/mcp/manifest et à chaque appel. Un outil hors périmètre répond Unknown tool: <name>, "exactly as a tool that does not exist" (exactement comme un outil qui n'existe pas), si bien qu'un client ne peut pas savoir ce qui manque à son jeton.

Étape 5. Créer le jeton et garder le secret

Nommez le jeton d'après l'agent ou l'environnement qui le détient, puis copiez le secret : "it is shown once, then only the prefix." (il est affiché une fois, puis seulement son préfixe.) Chaque jeton garde son propre workspace courant, si bien que deux agents sur deux jetons ne déplacent pas le pointeur l'un de l'autre.

Étape 6. N'autoriser les jetons d'exécution que pour un orchestrateur

Un jeton d'exécution est "a short-lived child of one of your tokens, minted for a single AEGIS run" (un enfant de courte durée de l'un de vos jetons, créé pour une seule exécution AEGIS), où AEGIS by 100monkeys.ai, in beta, est l'orchestrateur qui fait tourner l'agent. Un jeton ne peut créer d'enfants que si son propriétaire coche May mint execution tokens dans le formulaire du jeton. C'est désactivé par défaut, aucun preset ne l'active, et la documentation dit de "leave it off unless an orchestrator holds the token." (le laisser désactivé sauf si un orchestrateur détient le jeton.) L'outil de création n'est que dans le preset full.

Étape 7. Créer un jeton enfant pour une exécution

Le parent appelle tokens.mint_execution avec ces arguments :

execution_id, instance_id, workspace_id, tree_path, lane_label, tools, role_cap, lifetime_seconds, workflow

Une instance, un workspace, un chemin d'arbre, un label de lane, de 1 à 166 outils que le parent détient, un plafond de rôle égal à celui du parent ou viewer, et une durée de vie d'au plus 86 400 secondes qui ne dépasse jamais l'expiration du parent. workflow est facultatif : le nom de la porte d'une règle d'intégration que l'exécution fait tourner. La réponse :

{ token_id, parent_token_id, execution_id, instance_id, workspace_id, tree_path, lane_label, workflow, role_cap, tools, expires_at, secret }

Tout élargissement est refusé en une phrase et ne crée rien. Chaque écriture de l'enfant doit nommer sa lane et rester sous son chemin ; les refus de la documentation pour la lane forge/run-1 et le chemin apps/web :

This execution token writes only to lane "forge/run-1", not to the trunk.
This execution token writes only under "apps/web", not to "apps/api/x.ts".

Un enfant n'est jamais une seconde identité : chaque changement qu'il fait vous enregistre comme acteur, avec l'exécution pour laquelle il a été créé.

Étape 8. Révoquer, et lire le journal d'audit

L'enfant se révoque lui-même, ou son parent le révoque, avec tokens.revoke_execution ; il cesse aussitôt de s'authentifier sur le serveur qui l'a révoqué, et partout en 30 secondes. Révoquer le parent, ou changer son périmètre, révoque tous les enfants. Chaque appel d'outil entre dans le journal d'audit sous l'identité du jeton, et chaque création et révocation écrit une ligne d'audit qui nomme le parent, l'enfant et l'exécution.

Pour que l'approbation d'une exécution compte sur un trunk protégé, lisez notre guide Règles d'intégration : les code owners gardés au registre, avec un workflow AEGIS comme porte.

Ce que la documentation laisse sans réponse

• Un exemple complet. Le catalogue liste les arguments et la réponse de la création, mais ne montre aucun appel d'exemple.
• Le plafond d'outils. Un enfant prend de 1 à 166 outils alors que le preset full en contient 177 ; les outils qui ne peuvent pas passer à un enfant ne sont pas listés.
• Comment un orchestrateur reçoit le jeton parent. La documentation dit de n'autoriser la création que si un orchestrateur détient le jeton, mais pas comment AEGIS reçoit ce jeton.
• Où se trouvent les listes des presets. Les nombres sont donnés ; les noms des outils de chaque preset ne figurent que dans le sélecteur du formulaire.