Skip to main content

Define scopes

A scope is a named permission that a user grants to a specific AI client at consent time. It ends up as a string in the token's scope claim; your MCP server checks that string before allowing a tool call. The Scopes tab is where you decide which access labels exist for this Application.

New to scopes?

Read What is a scope? first if you've never modeled access for an API before — it explains the why in first principles. Then come back here for the how.

What the UI does​

The Scopes tab shows the current access-label set for this application. Starter scopes are seeded on registration:

  • rs-<id>:tools:read
  • rs-<id>:tools:write
  • rs-<id>:admin

You can create custom labels from a popover and delete unused labels through an impact preview. Scope IDs (the strings) are immutable once created — to "rename" a scope, create a new one and migrate mappings.

Naming convention​

The seeded pattern is <rs-prefix>:<resource>:<verb>:

  • rs-<uuid> namespaces the scope to this specific resource server. Tokens with this scope are bound to this server's aud; another server's SDK will reject them.
  • The middle segment (tools here) is the resource class. As your surface grows, add more — repos, issues, users, etc.
  • The verb at the end is the action level. read vs write is the floor; you can go finer.

The convention is just convention — the backend treats scope IDs as opaque strings. But picking something stable matters: scope IDs surface in tokens, audit logs, and your customers' OAuth client configurations. Renames are migrations.

For the design tradeoffs of read/write vs per-tool vs per-operation, see Scope design for MCP tools.

Where scopes come from at runtime​

When a user authorizes an OAuth client, they're shown a consent screen listing the scopes the client is asking for. The user grants some subset; that subset is what gets baked into the access token's scope claim.

The Go SDK validates tokens against this claim. If your echo_write tool is mapped to rs-xyz:tools:write and the caller's token only has rs-xyz:tools:read, the SDK returns 403 insufficient_scope.

Adding a custom scope​

Click Add label on the Scopes tab → pick a scope ID (e.g. rs-xyz:repos:admin) and a display name (what the consent screen shows users).

Custom scopes start unmapped. To make them functional, you need to map at least one tool to them on the Tools tab.

Deleting a scope​

The UI shows a delete button only if no tools are currently mapped to that scope. If you've mapped tools, unmap them first.

Deleting a scope that's referenced in an active access policy (e.g. the default role grants it) emits a scope_deleted drift event — visible on the Monitor tab — so you'll see the impact in audit logs.

Auto-suggested scopes from the SDK​

If you publish a manifest from the Go SDK with ToolScopeSuggestions populated, AuthSec stores those suggestions as suggested_scopes on each mcp_tools row. They show up in the UI as "SDK suggested: ..." hints when you're mapping. Suggestions never override admin choices — they're hints, not policy.

What changes after activation​

Once the application is launched (state = ready), deleting or modifying a scope that's actively in use shows up as a drift event in the Monitor tab. Existing access tokens issued before the change keep their scope claim until they expire; the next token issuance uses the new policy.