capsid_admin_manage_agents
Manage agents, on Capsid Admin. Needs the admin identity and the write grant.
What it does
The credential control plane. Admin only; mint, revoke and update_scopes need a recent sign-in from a signed-in session.
Scoped credentials: one row per caller, with its own key, scopes and audit identity (agent:<name>). Admin only, every action: a minted agent cannot mint, revoke or re-scope. The admin is an OAuth session on /mcp or a write-grant OPERATOR_KEY_HASH entry on /ops/mcp.
action "mint" creates an agent and returns its key once; only its sha256 is stored, so a lost key is replaced by revoking and minting again. It takes name (unique, revoked names included), kind (session | driver | seat | cron), namespaces (a list, or the single entry "*"), and optionally repos, tools, grants and flags. A new agent defaults to read on its namespaces with no flags. The flags are can_merge, can_direct_write, can_dispatch, can_write_workflows, can_touch_protected, money_paths, can_comment_pr.
action "list" returns every agent in the live table, revoked ones not yet archived included, with its scopes, last_seen and a 12-hex fingerprint of its key digest; never the stored verifier. With archived: true it returns the archive instead: revoked agents moved out of the live table by the watcher pass 7 days after revocation, or an old one-job runner key once its job ended, each with its reason, archived_at and the audit-row and job counts taken at the move. An archived name is never reused.
action "revoke" sets revoked_at, keeps the row, and the key stops resolving immediately.
action "update_scopes" replaces only the axes named: a call naming one flag leaves the others. Mint, revoke and update_scopes are audit-logged, never with the key.
What a client is told
The MCP hints it carries, so a client can ask before it acts (src/tool-annotations.ts).
- Writes: some action changes state.
- Can overwrite or remove what exists.
- A repeat can change things again.
- Stays inside Capsid.
Arguments
| Argument | Type | Needed | What it is |
|---|---|---|---|
action | one of: mint, list, revoke, update_scopes | always | mint | list | revoke | update_scopes. |
name | string | no | For mint, revoke and update_scopes: the agent's name. |
archived | boolean | no | For list: true returns the archived agents instead of the live table. |
kind | string | no | For mint: session | driver | seat | cron. Grants nothing by itself. |
namespaces | list of string | no | For mint (required) and update_scopes: the namespaces this agent may reach, or the single entry "*" for every one. |
repos | list of string | no | The repos this agent may reach, as "owner/name" entries, or the single entry "*". Omitted, the mint derives it from the namespaces' repo mapping, and refuses when a namespace maps no repo. A namespace scope of "*" derives "*". |
tools | list of string | no | Tool names this agent may call, or the single entry "*". Defaults to every tool its grant allows. An entry "tool.action" (for example "capsid_open_pr.comment") narrows that tool to the actions named. |
grants | list of one of: read, write | no | read, or read and write. A new agent gets read. |
flags | object | no | can_merge, can_direct_write, can_dispatch, can_write_workflows, can_touch_protected, money_paths, can_comment_pr. An absent flag is left unchanged. Each defaults to false at mint. |