MCP & agents
Permissions scoped per agent.
Two layers of scope: per-resource permissions (workspace / project / folder / document) and organisation capabilities (members, teams, billing, KG admin). Both are a strict ceiling on the underlying user — never an expansion.
The ceiling rule
Every tool resolves the agent's authority as the intersection of the user's role and the credential's grants:
effective(agent) = user_role ∩ credential_grant
Credentials can only narrow, never widen. Ticking a capability flag the underlying user's role doesn't already permit doesn't grant anything — the user's authority always wins. This applies identically to API keys and OAuth tokens.
Resource scope
A credential has three resource-scope dimensions:
- Workspaces — which workspaces the credential can see at all.
- Projects — within those workspaces, which projects.
- Permission level —
read,write,admin, ornone(explicit deny) per resource. Three domain-specific overrides (documents,improvements,plans) let an admin say “default project access except plans, where they must read explicitly.”
Organisation capabilities
Organisation capabilities sit alongside resource permissions. They're what gate every tool that touches org-level state — members, teams, billing, KG admin, settings, lifecycle. Without the corresponding flag, the relevant tools return accessDenied.
| Flag | Gates |
|---|---|
can_admin_org | updateOrganisation, updateOrgSettings |
can_manage_billing | Subscription, cancellation, credit purchase, seat-change |
can_manage_members | Invite, role change, deactivate, remove; workspace membership |
can_manage_teams | Team CRUD + workspace access grants |
can_manage_perms | upsertResourcePermission and friends |
can_manage_kg | All kg_admin tools (scope, rebuild, batch control) |
can_lifecycle | createWorkspace, createProject, updateWorkspace, updateProject |
The OAuth consent screen and the API-key admin UI share one component, so the user sees the same toggles either way. OAuth scopes (org_admin, org_billing, org_members, org_teams, org_permissions, org_settings, kg_admin, lifecycle) map 1:1 to these flags.
Default to least privilege
Managing credentials
Open Settings → MCP keys for API keys or Settings → OAuth clients for OAuth. You'll see every credential, its resource scope, its organisation capabilities, its last use timestamp, and a revoke button. Credentials are revocable without redeploying the agent.
Audit events
Every MCP-originated write is logged with the credential ID, tool name, request ID, and a metadata blob. The estimate-confirm-deduct ritual records the confirmation token alongside the action, so every credit- or money-spending operation has a complete preview→apply trail.
{
"label": "claude-on-laptop",
"type": "api_key",
"workspaces": ["c95d151a-…"],
"projects": ["767d20f4-…"],
"permissions": ["read", "write"],
"org_capabilities": {
"can_admin_org": false,
"can_manage_billing": false,
"can_manage_members": true,
"can_manage_teams": false,
"can_manage_perms": false,
"can_manage_kg": false,
"can_lifecycle": true
}
}