Limitare un token MCP di Carbon Forge a un solo agente

Anche in: English, Español, Português, 日本語, Deutsch, Français, 한국어, 简体中文, हिन्दी · Tutte le guide in italiano

Trasparenza: Carbon Forge è sviluppato da noi di 100monkeys.ai, quindi leggete questa guida come il resoconto di chi lo costruisce. L'ha scritta in bozza uno dei nostri agenti di IA a partire dalla documentazione pubblica (in inglese), soprattutto MCP token scopes (R#62460), MCP tokens (R#61824) e la Tokens catalog page (R#62188), e l'azienda l'ha rivista; questa edizione italiana è una traduzione della guida originale in inglese. Nomi dei preset, argomenti e frasi citate sono quelli della documentazione, le citazioni in inglese con la traduzione accanto; la documentazione non dà una chiamata di generazione completa, quindi mostriamo l'elenco degli argomenti invece di un esempio. Dove la documentazione lascia una domanda aperta, l'ultima sezione lo dice.

Due limiti su ogni token

Un token porta un tetto di ruolo (viewer, editor o admin) e un ambito degli strumenti, "the explicit set of MCP tools the bearer is allowed to call." (l'insieme esplicito degli strumenti MCP che il portatore può chiamare). Il tetto di ruolo è il limite superiore dei permessi; l'ambito lo restringe ancora. L'esempio della documentazione: un ambito SCM reader su un token admin restituisce lo stesso catalogo di strumenti dello stesso ambito su un token viewer.

Decidete cosa deve fare l'agente

Scrivete in una riga il compito dell'agente prima di aprire il modulo: recuperare e ragionare, prendere appunti, leggere codice, costruire su una lane o rilasciare. Ognuno corrisponde a un preset qui sotto. La regola della documentazione: "Default to the narrowest preset that still covers what the client needs." (partite dal preset più ristretto che copre ancora ciò che serve al client).

Impostate il tetto di ruolo

Aprite le impostazioni, scegliete API tokens e selezionate il workspace e un tetto di ruolo. I preset SCM indicano il ruolo a cui si abbinano: SCM reader con viewer, SCM agent e SCM release con editor.

Scegliete il preset più ristretto

I preset, con il numero di strumenti dato dalla documentazione (ognuno include cortex.ground):

• Read-only memory (read_only_memory, 14): leggere pagine e atom, cercare, seguire i link incrociati; nessuna scrittura.
• Basic LLM memory (basic_memory, 30): leggere e scrivere pagine, atom e tag, e cercare.
• Knowledge-graph reader (knowledge_graph_reader, 31): ogni superficie di contenuto e il grafo, nessuna scrittura.
• SCM reader (scm_reader, 58): alberi di codice, lane, changeset, cut e albero dei file, con pagine e ricerca; nessuna scrittura.
• SCM agent (scm_agent, 104): le letture SCM più la scrittura di pagine, atom, lane e alberi, il landing delle lane, i cut e il rendering.
• SCM release (scm_release, 67): le letture SCM più landing e approvazione delle lane, cut, push degli archivi e pubblicazione di un sito.
• Full access (full, 177): ogni strumento, entro il tetto di ruolo.

Un agente di sviluppo che costruisce su una lane riceve SCM agent; il revisore che approva riceve SCM release; un agente di ricerca riceve un reader. La documentazione riserva Full access a un client "trusted with anything the role can do" (fidato per tutto ciò che il ruolo può fare).

Usate Custom per uno strumento in più

Quando a un preset manca uno strumento, scegliete Custom e selezionate gli strumenti dal selettore raggruppato. L'esempio della documentazione è un agente di pubblicazione "that should be able to create comments but not pages" (che deve poter creare commenti ma non pagine). L'ambito è applicato all'elenco degli strumenti, al manifest su /api/mcp/manifest e a ogni chiamata. Uno strumento fuori ambito risponde Unknown tool: <name>, "exactly as a tool that does not exist" (esattamente come uno strumento che non esiste), così un client non può sapere cosa manca al suo token.

Generate il token e conservate il segreto

Date al token il nome dell'agente o dell'ambiente che lo detiene, poi copiate il segreto: "it is shown once, then only the prefix." (viene mostrato una volta, poi solo il prefisso). Ogni token mantiene il proprio workspace corrente, quindi due agenti con due token non si spostano il puntatore a vicenda.

Consentite i token di esecuzione solo a un orchestratore

Un token di esecuzione è "a short-lived child of one of your tokens, minted for a single AEGIS run" (un figlio di breve durata di uno dei vostri token, generato per una singola esecuzione AEGIS), dove AEGIS by 100monkeys.ai, in beta, è l'orchestratore che esegue l'agente. Un token può generare figli solo se il suo proprietario spunta May mint execution tokens (può generare token di esecuzione) nel modulo del token. È disattivato per impostazione predefinita, nessun preset lo attiva, e la documentazione dice di "leave it off unless an orchestrator holds the token." (lasciarlo spento a meno che il token non sia detenuto da un orchestratore). Lo strumento di generazione è solo nel preset full.

Generate un token figlio per una esecuzione

Il genitore chiama tokens.mint_execution con questi argomenti:

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

Un'istanza, un workspace, un percorso dell'albero, un'etichetta di lane, da 1 a 166 strumenti che il genitore possiede, un tetto di ruolo pari a quello del genitore o viewer, e una durata di al massimo 86.400 secondi che non supera mai la scadenza del genitore. workflow è facoltativo: il nome del gate di una regola di landing che l'esecuzione esegue. La risposta:

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

Ogni allargamento viene rifiutato con una frase e non genera nulla. Ogni scrittura del figlio deve indicare la sua lane e restare sotto il suo percorso; i rifiuti della documentazione per la lane forge/run-1 e il percorso 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 figlio non è mai una seconda identità: ogni modifica che fa registra voi come autore e l'esecuzione per cui è stato generato.

Revocate, e leggete il registro di audit

Il figlio si revoca da solo, oppure lo revoca il genitore, con tokens.revoke_execution; smette subito di autenticarsi sul server che lo ha revocato ed entro 30 secondi ovunque. Revocare il genitore, o cambiarne l'ambito, revoca tutti i figli. Ogni chiamata a uno strumento finisce nel registro di audit con l'identità del token, e ogni generazione e revoca scrive una riga di audit con genitore, figlio ed esecuzione.

Per far valere l'approvazione di un'esecuzione su un trunk protetto, leggete la nostra guida Regole di landing: i code owner tenuti nel registro, con un workflow AEGIS come gate.

Cosa lascia senza risposta la documentazione

• Un esempio completo. Il catalogo elenca argomenti e risposta della generazione ma non mostra una chiamata di esempio.
• Il tetto degli strumenti. Un figlio prende da 1 a 166 strumenti mentre il preset full ne ha 177; quali strumenti non possano passare a un figlio non è elencato.
• Come un orchestratore riceve il token genitore. La documentazione dice di consentire la generazione solo quando un orchestratore detiene il token, ma non come quel token venga dato ad AEGIS.
• Dove stanno gli elenchi dei preset. I numeri sono dati; i nomi degli strumenti di ogni preset sono solo nel selettore del modulo.