Acota un token MCP de Carbon Forge a un solo agente

También en: English, Português, 日本語, Deutsch, Français, 한국어, 简体中文, Italiano, हिन्दी · Todas las guías en español

Aviso: construimos Carbon Forge en 100monkeys.ai, así que lee esto como el relato de quien lo fabrica. Esta guía la redactó uno de nuestros agentes de IA a partir de la documentación pública, sobre todo MCP token scopes (R#62460), MCP tokens (R#61824) y la página Tokens del catálogo (R#62188), y la revisó la empresa; esta versión en español es una traducción de la guía original en inglés. Los nombres de los presets, los argumentos y las frases citadas son de la documentación, y las citas van en inglés con la traducción al lado; la documentación no da ninguna llamada de creación completa, así que se muestra la lista de argumentos en lugar de un ejemplo. Donde la documentación deja una pregunta abierta, la última sección lo dice.

Dos límites en cada token

Un token lleva un rol máximo (viewer, editor o admin) y un alcance de herramientas, "the explicit set of MCP tools the bearer is allowed to call." (el conjunto explícito de herramientas MCP que su portador puede llamar). El rol máximo es el techo de permisos; el alcance lo estrecha aún más. El ejemplo de la documentación: un alcance SCM reader en un token admin devuelve el mismo catálogo de herramientas que el mismo alcance en un token viewer.

Paso 1. Decide qué debe hacer el agente

Escribe el trabajo del agente en una línea antes de abrir el formulario: recuperar y razonar, tomar notas, leer código, construir en una lane o publicar. Cada uno corresponde a un preset de abajo. La regla de la documentación: "Default to the narrowest preset that still covers what the client needs." (Por defecto, el preset más estrecho que aún cubra lo que el cliente necesita).

Paso 2. Fija el rol máximo

Abre los ajustes, elige API tokens y escoge el espacio de trabajo y un rol máximo. Los presets SCM dicen con qué rol van: SCM reader con viewer, SCM agent y SCM release con editor.

Paso 3. Elige el preset más estrecho

Los presets, con el número de herramientas que da la documentación (cada uno incluye cortex.ground):

• Read-only memory (read_only_memory, 14): leer páginas y átomos, buscar, seguir enlaces cruzados; sin escrituras.
• Basic LLM memory (basic_memory, 30): leer y escribir páginas, átomos y etiquetas, y buscar.
• Knowledge-graph reader (knowledge_graph_reader, 31): todas las superficies de contenido y el grafo, sin escrituras.
• SCM reader (scm_reader, 58): árboles de código, lanes, changesets, cortes y el árbol de archivos, con páginas y búsqueda; sin escrituras.
• SCM agent (scm_agent, 104): las lecturas SCM más escribir páginas, átomos, lanes y árboles, integrar lanes, cortar y renderizar.
• SCM release (scm_release, 67): las lecturas SCM más integrar y aprobar lanes, cortar, enviar archivos y publicar un sitio.
• Full access (full, 177): todas las herramientas, dentro del rol máximo.

Un agente de código que construye en una lane recibe SCM agent; el revisor que aprueba, SCM release; un agente de investigación, un lector. La documentación reserva Full access para un cliente "trusted with anything the role can do" (de confianza para todo lo que el rol puede hacer).

Paso 4. Usa Custom para una herramienta más

Cuando a un preset le falta una herramienta, elige Custom y escoge herramientas en el selector agrupado. El ejemplo de la documentación es un agente de publicación "that should be able to create comments but not pages" (que debe poder crear comentarios pero no páginas). El alcance se aplica en la lista de herramientas, en el manifiesto de /api/mcp/manifest y en cada llamada. Una herramienta fuera de él responde Unknown tool: <name>, "exactly as a tool that does not exist" (exactamente como una herramienta que no existe), así que un cliente no puede saber lo que le falta a su token.

Paso 5. Crea el token y guarda el secreto

Ponle al token el nombre del agente o del entorno que lo tiene y copia el secreto: "it is shown once, then only the prefix." (se muestra una vez y después solo el prefijo). Cada token guarda su propio espacio de trabajo actual, así que dos agentes con dos tokens no se mueven el puntero el uno al otro.

Paso 6. Permite tokens de ejecución solo a un orquestador

Un token de ejecución es "a short-lived child of one of your tokens, minted for a single AEGIS run" (un hijo de vida corta de uno de tus tokens, creado para una sola ejecución de AEGIS), donde AEGIS by 100monkeys.ai, in beta, es el orquestador que ejecuta el agente. Un token solo puede crear hijos si su dueño marca May mint execution tokens en el formulario del token. Está desactivado por defecto, ningún preset lo activa, y la documentación dice "leave it off unless an orchestrator holds the token." (déjalo desactivado salvo que el token lo tenga un orquestador). La herramienta de creación solo está en el preset full.

Paso 7. Crea un token hijo para una ejecución

El padre llama a tokens.mint_execution con estos argumentos:

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

Una instancia, un espacio de trabajo, una ruta del árbol, una etiqueta de lane, de 1 a 166 herramientas que tenga el padre, un rol máximo igual al del padre o viewer, y una vida de 86.400 segundos como mucho que nunca supera la caducidad del padre. workflow es opcional: el nombre de la puerta de una regla de integración que ejecuta la ejecución. La respuesta:

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

Cualquier ampliación se rechaza con una frase y no crea nada. Cada escritura del hijo debe nombrar su lane y quedarse bajo su ruta; los rechazos de la documentación para la lane forge/run-1 y la ruta 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 hijo nunca es una segunda identidad: cada cambio que hace te registra a ti como actor, junto con la ejecución para la que se creó.

Paso 8. Revoca y lee el registro de auditoría

El hijo se revoca a sí mismo, o lo revoca su padre, con tokens.revoke_execution; deja de autenticar al instante en el servidor que lo revocó y en 30 segundos en todos. Revocar el padre, o cambiar su alcance, revoca todos los hijos. Cada llamada a herramienta queda en el registro de auditoría bajo la identidad del token, y cada creación y revocación escribe una fila de auditoría que nombra padre, hijo y ejecución.

Para que la aprobación de una ejecución cuente en un trunk protegido, lee nuestra guía Reglas de integración: los code owners guardados en el registro, con un workflow de AEGIS como puerta.

Lo que la documentación deja sin responder

• Un ejemplo completo. El catálogo enumera los argumentos y la respuesta de la creación, pero no muestra ninguna llamada de ejemplo.
• El techo de herramientas. Un hijo acepta de 1 a 166 herramientas mientras el preset full tiene 177; no se dice qué herramientas no pueden pasar a un hijo.
• Cómo recibe un orquestador el token padre. La documentación dice que solo se permita crear hijos cuando un orquestador tiene el token, pero no cómo se le da ese token a AEGIS.
• Dónde están las listas de cada preset. Se dan los números; los nombres de las herramientas de cada preset solo están en el selector del formulario.