Restrinja um token MCP do Carbon Forge a um só agente

Também em: English, Español, 日本語, Deutsch, Français, 한국어, 简体中文, Italiano, हिन्दी · Todos os guias em português

Aviso: desenvolvemos o Carbon Forge na 100monkeys.ai, então leia isto como o relato de quem o fabrica. Este guia foi redigido por um dos nossos agentes de IA a partir da documentação pública, principalmente MCP token scopes (R#62460), MCP tokens (R#61824) e a página Tokens do catálogo (R#62188), e revisado pela empresa; esta versão em português é uma tradução do guia original em inglês. Os nomes dos presets, os argumentos e as frases citadas são da documentação, e as citações ficam em inglês com a tradução ao lado; a documentação não dá nenhuma chamada de criação completa, então mostramos a lista de argumentos em vez de um exemplo. Onde a documentação deixa uma pergunta em aberto, a última seção diz isso.

Dois limites em cada token

Um token carrega um papel máximo (viewer, editor ou admin) e um escopo de ferramentas, "the explicit set of MCP tools the bearer is allowed to call." (o conjunto explícito de ferramentas MCP que o portador pode chamar). O papel máximo é o teto de permissão; o escopo o estreita ainda mais. O exemplo da documentação: um escopo SCM reader num token admin devolve o mesmo catálogo de ferramentas que o mesmo escopo num token viewer.

Passo 1. Decida o que o agente precisa fazer

Escreva o trabalho do agente numa linha antes de abrir o formulário: buscar e raciocinar, tomar notas, ler código, construir numa lane ou publicar. Cada um corresponde a um preset abaixo. A regra da documentação: "Default to the narrowest preset that still covers what the client needs." (Por padrão, o preset mais estreito que ainda cubra o que o cliente precisa).

Passo 2. Defina o papel máximo

Abra as configurações, escolha API tokens e selecione o workspace e um papel máximo. Os presets SCM dizem com que papel combinam: SCM reader com viewer, SCM agent e SCM release com editor.

Passo 3. Escolha o preset mais estreito

Os presets, com as contagens de ferramentas da documentação (cada um inclui cortex.ground):

• Read-only memory (read_only_memory, 14): ler páginas e átomos, buscar, seguir links cruzados; sem escrita.
• Basic LLM memory (basic_memory, 30): ler e escrever páginas, átomos e tags, e buscar.
• Knowledge-graph reader (knowledge_graph_reader, 31): todas as superfícies de conteúdo e o grafo, sem escrita.
• SCM reader (scm_reader, 58): árvores de código, lanes, changesets, cortes e a árvore de arquivos, com páginas e busca; sem escrita.
• SCM agent (scm_agent, 104): as leituras SCM mais escrever páginas, átomos, lanes e árvores, integrar lanes, cortar e renderizar.
• SCM release (scm_release, 67): as leituras SCM mais integrar e aprovar lanes, cortar, enviar arquivos e publicar um site.
• Full access (full, 177): todas as ferramentas, dentro do papel máximo.

Um agente de código que constrói numa lane recebe SCM agent; o revisor que aprova, SCM release; um agente de pesquisa, um leitor. A documentação reserva Full access para um cliente "trusted with anything the role can do" (confiável para tudo o que o papel pode fazer).

Passo 4. Use Custom para uma ferramenta a mais

Quando falta uma ferramenta num preset, escolha Custom e selecione ferramentas no seletor agrupado. O exemplo da documentação é um agente de publicação "that should be able to create comments but not pages" (que deve poder criar comentários, mas não páginas). O escopo vale na lista de ferramentas, no manifesto em /api/mcp/manifest e em cada chamada. Uma ferramenta fora dele responde Unknown tool: <name>, "exactly as a tool that does not exist" (exatamente como uma ferramenta que não existe), então um cliente não consegue saber o que falta ao seu token.

Passo 5. Crie o token e guarde o segredo

Dê ao token o nome do agente ou do ambiente que o usa e copie o segredo: "it is shown once, then only the prefix." (ele aparece uma vez, depois só o prefixo). Cada token guarda o seu próprio workspace atual, então dois agentes com dois tokens não movem o ponteiro um do outro.

Passo 6. Permita tokens de execução só para um orquestrador

Um token de execução é "a short-lived child of one of your tokens, minted for a single AEGIS run" (um filho de vida curta de um dos seus tokens, criado para uma única execução do AEGIS), em que AEGIS by 100monkeys.ai, in beta, é o orquestrador que executa o agente. Um token só pode criar filhos quando o dono marca May mint execution tokens no formulário do token. Vem desligado, nenhum preset o liga, e a documentação diz "leave it off unless an orchestrator holds the token." (deixe desligado, a menos que um orquestrador tenha o token). A ferramenta de criação só está no preset full.

Passo 7. Crie um token filho para uma execução

O pai chama tokens.mint_execution com estes argumentos:

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

Uma instância, um workspace, um caminho na árvore, um rótulo de lane, de 1 a 166 ferramentas que o pai tenha, um papel máximo igual ao do pai ou viewer, e uma vida de no máximo 86.400 segundos que nunca passa da expiração do pai. workflow é opcional: o nome do portão de uma regra de integração que a execução executa. A resposta:

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

Qualquer ampliação é recusada com uma frase e não cria nada. Toda escrita do filho precisa nomear a sua lane e ficar sob o seu caminho; as recusas da documentação para a lane forge/run-1 e o caminho 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".

Um filho nunca é uma segunda identidade: cada mudança que ele faz registra você como autor, junto com a execução para a qual foi criado.

Passo 8. Revogue e leia o log de auditoria

O filho revoga a si mesmo, ou o pai o revoga, com tokens.revoke_execution; ele para de autenticar na hora no servidor que o revogou e em até 30 segundos em todos. Revogar o pai, ou mudar o escopo dele, revoga todos os filhos. Cada chamada de ferramenta entra no log de auditoria sob a identidade do token, e cada criação e revogação grava uma linha de auditoria com pai, filho e execução.

Para que a aprovação de uma execução conte num trunk protegido, leia nosso guia Regras de integração: os code owners guardados no registro, com um workflow do AEGIS como portão.

O que a documentação deixa sem resposta

• Um exemplo completo. O catálogo lista os argumentos e a resposta da criação, mas não mostra nenhuma chamada de exemplo.
• O teto de ferramentas. Um filho aceita de 1 a 166 ferramentas enquanto o preset full tem 177; quais ferramentas não podem passar para um filho não é dito.
• Como um orquestrador recebe o token pai. A documentação diz para permitir a criação só quando um orquestrador tem o token, mas não como o AEGIS recebe esse token.
• Onde ficam as listas de cada preset. As contagens são dadas; os nomes das ferramentas de cada preset só estão no seletor do formulário.