Entitlements and the MCP tool tiers

Every SupaCloud agent session is granted a minimum surface and optionally elevated through an agent profile. Understanding how edition, entitlements, and MCP capability tiers compose helps you reason about what an agent can (and cannot) do — and why.

The two gates

Before an agent can act, two independent gates must allow it.

Gate 1 — deployment edition. The SupaCloud instance runs either Community or Enterprise edition. Edition is a process-global, fail-closed property: enterprise features (including SSO, advanced seat types, and certain entitlement overrides) are simply unavailable on a Community instance regardless of what an individual workspace or agent profile requests. A seat can never grant an edition-gated feature.

Gate 2 — MCP capability allowlist. Every MCP tool belongs to a tier. A task session only has access to the tools explicitly allowed by the agent profile (or the workspace default profile). The two gates are independent — edition does not automatically broaden the MCP allowlist.

MCP tool tiers

The 49 MCP tools are split across five allowlist tiers:

Baseline (supacloud.*)

Always-on floor for every authenticated agent session — unconditionally granted regardless of the allowlist. Covers subtask delegation, read-only memory, outcome telemetry, and memory.propose_review.

Read tier (supacloud.read.*)

Situational-awareness reads: workspace info, project and task listings, runner status, schedules, resources, apps, and workflows. Metadata only — no secrets, no connection strings.

Ops tier (supacloud.ops.*)

Operational triggers: start a workflow run, manage schedules, trigger a repo sync. script.run is an ops-tier tool that requires an additional explicit grant (supacloud.script.run) due to its indirect resource and secret access.

Scaffold tier (supacloud.scaffold.*)

Create proposals and spawn scaffold tasks. Enables agent-driven planning workflows that propose work items and fan out subordinate tasks without requiring full ops or deploy permissions.

Deploy tier (supacloud.deploy.*)

Deployment actions: deploy or undeploy an app, apply app migrations. Requires supacloud.deploy.* in the profile allowlist plus the task actor must be an owner or admin of the workspace — both checks must pass.

supacloud.full grants all five tiers at once.

Baseline is always on

The N+4 baseline is granted unconditionally — a task with an empty allowlist still gets delegation, memory, and telemetry. The baseline was previously gated behind supacloud.*; that gate was removed (ADR 0033).

Profile-less tasks and workspace defaults

A task without an agent profile resolves to a read-only surface (supacloud.read.* plus the unconditional baseline). Ops and deploy tiers stay fail-closed.

Workspace administrators can promote a workspace-default agent profile — the one profile flagged is_workspace_default — from Settings → Agent Profiles: open a profile and choose Set as workspace default (a workspace can have at most one, so promoting a profile clears the previous default). When set, all profile-less tasks in that workspace inherit its allowlist instead of the hard-coded read-only fallback.

Rate limits

Capability tiers carry tiered rate limits that apply at multiple scopes:

Tier	Per task	Per workspace / day	Per profile / hour
Read	50 calls	—	—
Ops	10 calls	100 calls	30 calls
Scaffold	10 calls	10 proposals + 3 task-spawns	10 proposals + 3 task-spawns
Deploy	5 calls	20 calls	10 calls

Workspace and profile caps guard against delegation chains multiplying per-task budgets across many child tasks. Counters are derived from audit_events — they survive server restarts.

Deploy-tier confirmation

app.deploy and app.migration.apply use a stateless two-step confirmation to prevent accidental runs. The first call (no token) returns a signed confirmation_token and a changes_summary. The agent must call again with that token to proceed. The token is HMAC-signed with a server-side secret (SUPACLOUD_MCP_CONFIRMATION_SECRET); if the secret is absent the tools fail closed.

Entitlement priority

When both edition and MCP allowlists permit an action, the workspace’s own entitlement resolution still applies:

user override → seat type → workspace override → organization plan → default

A seat type granted by the organization can therefore narrow or broaden what an agent sees through workspace-level workspace info reads — but it cannot elevate an agent past what the deployment edition permits.

Tip

For a complete listing of every MCP tool name and its parameters, see the developer MCP reference at the MCP tool surface reference. For how workspaces and organizations fit together, see Workspaces and Organizations.