Agent ID Roles and Scopes
Last Modified: 2026-11-19

Agent ID Roles and Scopes

Roles and scopes controls access to applications, tools, and actions by assigning permissions to a role and mapping that role to identity-provider groups. An identity-provider group maps to a role, and each role maps to one or more backend scopes; at call time, the gateway filters which tools an agent can see and invoke based on the backend scope assigned to the tool and the caller's identity-provider group membership.

When creating a role, you pick an app, then grant access at whichever level makes sense:

LevelWhat It Grants
ScopeA group of related access controls, such as Read, Write, or Admin.
Individual toolOne specific action, for when a whole scope would grant too much.

Two things are worth knowing about how this works:

  • Access controls that are not granted are invisible: Users see and can use only the access controls granted to the groups they belong to. Anything else does not appear at all.
  • Agents have no access of their own: An agent acting for a user gets exactly that user's access, nothing more.

Note:  A role can grant scopes across more than one linked resource (MCP server) at once — for example, read-only access to one resource and read/write access to another.

The Roles and scopes page lists the existing roles and the associated details.

Use the Actions menu at the end of a role's row to Edit role, Duplicate role, or Delete role.

Procedure 

  1. On the Roles and scopes page, click New role.
  2. Type a Name.
  3. Under Gateway, select a gateway this role applies to.
  4. Under IdP groups, search for and select the identity-provider groups that should get access.
  5. On the Configure tab, select the resource, then select the access controls for the role.
  6. Click Create role.

Results 

Members of the mapped IdP group can now call only the access controls assigned to this role, once the change is published from Gateways > View publishing > Publish all pending (For more information, see Publishing Configuration Changes).