Scope a Carbon Forge MCP token to one agent

Also in: Español, Português, 日本語, Deutsch, Français, 한국어, 简体中文, Italiano, हिन्दी

Disclosure: we build Carbon Forge at 100monkeys.ai, so read this as a maker's account. This guide was drafted by one of our AI agents from the public docs, chiefly MCP token scopes (R#62460), MCP tokens (R#61824) and the Tokens catalog page (R#62188), and reviewed by the company. Preset names, arguments and quoted sentences are the docs' own; the docs give no worked mint call, so the argument list is shown rather than a sample. Where the docs leave a question open, the last section says so.

Two limits on every token

A token carries a role cap (viewer, editor or admin) and a tool-scope, "the explicit set of MCP tools the bearer is allowed to call." The role cap is the upper bound on permission; the scope narrows it further. The docs' example: an SCM reader scope on an admin token returns the same tool catalog as the same scope on a viewer token.

Step 1. Decide what the agent must do

Write down the agent's job in one line before you open the form: retrieve and reason, keep notes, read code, build on a lane, or release. Each maps to a preset below. The docs' rule: "Default to the narrowest preset that still covers what the client needs."

Step 2. Set the role cap

Open settings, pick API tokens, and choose the workspace and a role cap. The SCM presets name the role they pair with: SCM reader with viewer, SCM agent and SCM release with editor.

Step 3. Pick the narrowest preset

The presets, with the docs' tool counts (each includes cortex.ground):

• Read-only memory (read_only_memory, 14): read pages and atoms, search, follow cross-links; no writes.
• Basic LLM memory (basic_memory, 30): read and write pages, atoms and tags, and search.
• Knowledge-graph reader (knowledge_graph_reader, 31): every content surface and the graph, no writes.
• SCM reader (scm_reader, 58): code trees, lanes, changesets, cuts and the file tree, with pages and search; no writes.
• SCM agent (scm_agent, 104): the SCM reads plus writing pages, atoms, lanes and trees, landing lanes, cutting and rendering.
• SCM release (scm_release, 67): the SCM reads plus landing and approving lanes, cutting, pushing archives and publishing a site.
• Full access (full, 177): every tool, within the role cap.

A coding agent that builds on a lane gets SCM agent; the reviewer that approves gets SCM release; a research agent gets a reader. The docs keep Full access for a client "trusted with anything the role can do".

Step 4. Use Custom for one extra tool

When a preset is one tool short, pick Custom and choose tools from the grouped picker. The docs' example is a publishing agent "that should be able to create comments but not pages". The scope is enforced on the tool list, on the manifest at /api/mcp/manifest and on every call. A tool outside it answers Unknown tool: <name>, "exactly as a tool that does not exist", so a client cannot learn what its token lacks.

Step 5. Mint the token and keep the secret

Name the token after the agent or environment that holds it, then copy the secret: "it is shown once, then only the prefix." Each token keeps its own current workspace, so two agents on two tokens do not move each other's pointer.

Step 6. Allow execution tokens only for an orchestrator

An execution token is "a short-lived child of one of your tokens, minted for a single AEGIS run", where AEGIS by 100monkeys.ai, in beta, is the orchestrator running the agent. A token can mint children only when its owner ticks May mint execution tokens in the token form. It is off by default, no preset sets it, and the docs say to "leave it off unless an orchestrator holds the token." The mint tool is in the full preset only.

Step 7. Mint a child token for one run

The parent calls tokens.mint_execution with these arguments:

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

One instance, one workspace, one tree path, one lane label, 1 to 166 tools the parent holds, a role cap of the parent's or viewer, and a lifetime of at most 86,400 seconds that never passes the parent's expiry. workflow is optional: the name of a landing rule's gate the run executes. The answer:

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

Any widening is refused with one sentence and mints nothing. Every write the child makes must name its lane and stay under its path; the docs' refusals for lane forge/run-1 and path 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".

A child is never a second identity: every change it makes records you as the actor and the run it was minted for.

Step 8. Revoke, and read the audit log

The child revokes itself, or its parent revokes it, with tokens.revoke_execution; it stops authenticating at once on the server that revoked it and within 30 seconds everywhere. Revoking the parent, or changing its scope, revokes every child. Every tool call lands in the audit log under the token identity, and every mint and revoke writes an audit row naming parent, child and run.

To make a run's approval count on a protected trunk, read our guide Landing rules: code owners in the record, AEGIS as a gate.

What the docs leave unanswered

• A worked example. The catalog lists the mint's arguments and answer but shows no sample call.
• The tool ceiling. A child takes 1 to 166 tools while the full preset holds 177; which tools cannot pass to a child is not listed.
• How an orchestrator receives the parent token. The docs say to allow minting only when an orchestrator holds it, but not how AEGIS is given that token.
• Where the preset lists live. The counts are given; the per-preset tool names are only in the form's picker.