Scope times role

Agents and MCPMCPHTTPmcp:readmcp:fullcreate_bot_api_keymcp.exposure.readOnlygate

A key's scope decides read or write; the account's roles decide which tools and which records. Both must pass on every call.

The situation

An investigator agent should read production freely and change nothing. An operator agent should resolve reviewer rows and nothing else. One key per agent, and the rules should be the same ones people already live under.

The recipe

Create a service account, give it roles, then mint a key with a scope:

{ "id": "<bot account id>", "name": "prod-investigator", "scopes": ["mcp:read"] }

Scope	Tools that appear
`mcp:read`	Listing, searching, diagnosing, stats, exports: anything that only reports
`mcp:full`	Those, plus tools that change state: create, claim and resolve escalations, invoke workflows, update configuration

Each tool also declares the capability its caller needs (caller, admin, builder, role manager, superadmin), and a tool appears only to accounts that hold it. Within a tool, the account’s role decides whether the action is allowed on a given record. To make a whole deployment read-only for every key and OAuth grant, set mcp.exposure.readOnly in start().

The guarantee

Scope is read or write; role is which tools and which records. An account with mcp:full and only the reviewer role can resolve reviewer escalations, and cannot route work to finance or manage users. Resolving with admin_resolve_escalation needs mcp:full and write access to the row’s role; reading the same queue with find_escalations needs only mcp:read. A tool with no gate is not exposed at /mcp. See MCP.

Agents and MCP