Roles and Permissions

Roles and Permissions control what each member and agent can do: define roles, grant their scopes, and turn denied requests into precise grants. Open the page from Organization settings > Team > Roles & Permissions in the dashboard.

The page contains two tabs: Roles, with the role count shown, and Authorization Challenges. Role assignment for people happens inside each role (see the role editor) and from the Manage roles action on the Members page.

To give a team’s members their MCP tools through a role’s plugin, follow Automatic MCP distribution. Role membership can be assigned here or managed through directory sync.

Access requirements

Viewing this page requires the org:read scope, which both the Admin and Member default roles include. Creating, editing, or deleting roles and assigning roles to members requires the org:admin scope, held only by Admins by default.

Roles

The Roles tab lists every role with its name, description, permissions, and members, and explains the two system roles beneath the list. Click Add Role to create a role, or a role’s edit action to change it. Both open the role editor, where resource-scoped permission rules are added, down to individual MCP servers and tool selectors. These are the same rules that appear on each MCP server’s and gateway’s Team Access tab (see Team access): a role granted access on a server’s tab is exactly what the editor writes when mcp:connect is added and narrowed to that one server. Direct rules are editable on the server’s tab, which links back here through Edit in Role Manager; organization-level rules appear there too and link back to the role that owns them. Changing one on a server’s tab applies to that server only, as a block on that server. A block naming the administrator role is refused on that tab so admins cannot lock themselves out.

Roles can also be assigned to registered agents through the Assign Agents section of the role editor, and an MCP server’s Grant access menu offers a Person or an Agent. Once a role has agent members, permission rows for scopes agents cannot hold are marked Not available to agents. See Agent identity.

Remote and tunneled servers can be permissioned by tool name, the same as any other server. Expanding a remote server in the Specific tools picker lists the tools recorded for it. A server whose tools have never been recorded has nothing to list, and the picker links to that server’s Inspect tab instead, where connecting to the live server records them. See Recording tool metadata.

The role editor

Creating or editing a role opens a full page at Roles & Permissions > Create role or Edit role. The page describes roles as carrying permissions that enable access to features, some of which can be narrowed to include or exclude certain resources. It has three parts:

• Permissions. Click Add permissions to pick scopes from one searchable menu. Selected permissions split into MCP access and Platform access, and each MCP permission row carries its own narrowing control: All servers, Specific projects (servers within selected projects), Specific servers, or Specific tools. Pickers lead with a Selected (n) group so the servers, projects, or tools already chosen are visible without scrolling, and rows read server · project so same-named servers in different projects stay distinguishable.
• Assign Members. Choose which organization members hold the role. When Directory Sync (SCIM) is enabled, the list still renders so current holders are visible, but rows are read-only behind a Managed by directory sync notice and the header reads (N assigned by directory sync); assignment happens in the identity provider’s group mapping instead. See IDP and SSO.
• Assign Agents. Choose which agent identities hold the role. This section is never gated on Directory Sync, because a directory syncs people, not agents. Scopes an agent cannot hold are marked as not agent-eligible; an agent’s grants are filtered against the agent runtime scope allowlist when loaded, so a role cannot hand an agent a scope it could not be granted directly. See Agent identity.

Scopes

A role is a set of scopes. Each scope unlocks a slice of the platform:

Scope	What it makes available	Implies
org:read	View organization pages: team, billing usage, audit logs, domains, and settings	—
org:admin	Organization administration: invites and role assignment, API keys, billing actions, organization settings, and the Observability and Security and Policy sections	org:read
project:read	View project surfaces: sources, deployments, and the catalog	—
project:write	Add and modify sources, retry deployments, and manage plugins	project:read
mcp:read	View MCP servers and their configuration	mcp:connect
mcp:connect	Connect to MCP servers and call their tools, in the playground and from clients	—
mcp:write	Create and configure MCP servers, curate tools, and add catalog servers	mcp:read, mcp:connect
environment:read	View environments and their entries	—
environment:write	Create environments and manage their variables and secrets	environment:read
skill:read	View skills and their manifests	—
skill:write	Add and version skills	skill:read
assistant:read	View assistants and chat with them, including the Project Assistant	—
assistant:write	Create, edit, and delete assistants, and change their status and instructions	assistant:read
chat:read	Read other members’ agent session transcripts in Agent Sessions and pin them	—
chat:write	Delete other members’ sessions, rename them, and submit feedback on them	chat:read
agent:read, agent:write, agent:authorize, agent:transfer	View, manage, authorize, and transfer ownership of agent identities	—

Write scopes imply their read counterparts, so a role granting mcp:write never needs mcp:read added separately. A role needs only mcp:connect on a server to connect and call its tools, including for a private tunneled server; project:read and project:write are not required. Every member can always read and change sessions they own; chat:read and chat:write govern other people’s sessions.

Skill and assistant scopes are separate from project scopes: project:write does not grant assistant:write, and assistant:write does not grant project:write. Assistant triggers still use project:read and project:write. The Admin and Member roles include their assistant scopes automatically, but custom roles do not, so add assistant:read or assistant:write to any custom role that needs assistant access. Attaching skills to an assistant also requires skill:read, and attaching an MCP server requires mcp:connect on that server.

An assistant grant covers one of three ranges:

• All assistants in the organization.
• Specific projects: every assistant in the selected projects, including creating new ones there.
• A single assistant: only that assistant. This grant cannot create assistants or see other assistants in the project. The role editor offers the first two options; single-assistant grants are created through the API.

Agent policies can also include assistant:read and assistant:write with the same ranges, so an agent can, for example, hold assistant:write on its own assistant only. See Agent identity.

Each read, write, and connect scope also has a blocking counterpart (for example mcp:blocked_connect). A blocking rule withdraws that scope for the matching resources even when another role grants it, which is how a server’s Access page can exclude one principal without editing every role. The platform refuses to write a block against a principal the caller holds, since a block on mcp:* would also remove the read that renders the page. Blocking scopes cannot be written against agents.

Transcript access is never a default

No role includes chat:read or chat:write by default, including Admin. Grant them through a custom role only where transcript review is required; every transcript open is audit-logged. The setup wizard’s Enable logging step offers to create a Session Auditor custom role carrying chat:read for exactly this purpose.

System roles

Two preset roles ship with the platform:

Role	Scopes	Effective access
Admin	Every standard scope	Full administration: manage the organization, all projects, servers, environments, skills, and assistants, plus the Observability and Security and Policy sections
Member	org:read, project:read, mcp:read, mcp:connect, skill:read, assistant:read	Read and connect: browse the org and projects, view servers, skills, and assistants, chat with assistants, and use tools, with no write access, environment access, or org administration

Member is the baseline every invited or directory-synced member receives, so editing a system role changes access for everyone holding it at once: widening Member raises the floor for the whole organization, and narrowing Admin risks cutting administrators off from management surfaces (the platform refuses to remove the last admin, but won’t stop an over-narrowed Admin role). For targeted needs, prefer creating a custom role and granting it to specific members over editing the presets.

Members

Role assignment for members no longer has its own tab. A member can hold several roles; their access is the union of all of them. Assign roles in three places:

• In the role editor, under Assign Members, to add or remove many members from one role.
• From the Manage roles action on the Members page, to change every role one member holds, including system roles.
• From a denied authorization challenge, to grant the custom role whose permissions cover the denied action.

When Directory Sync (SCIM) is enabled, a notice at the top of the page states that roles are assigned from the identity provider rather than here, and links to Manage identity settings.

Authorization challenges

The Authorization Challenges tab lists past denied-access events: who tried to do what, and which scope the request was missing. Filter pills switch between Denied, Resolved, and All, each with a count, and dropdowns narrow the list by principal (Everyone by default) and scope (All scopes). Each row carries an outcome badge: Denied means the principal lacked the required scope or grants, Allowed records a permitted check, and Resolved marks a denial that was answered by granting access. Unresolved challenges also surface on the organization home page, and each identity’s Access tab on Identities shows this log filtered to that person or agent.

Challenges are actionable. Opening a denied challenge leads into the Grant Access flow: pick a custom role whose grants cover the denied action, and the platform assigns that role to the member, keeping every role they already hold, before recording the challenge as resolved. Subsequent attempts succeed without the member re-requesting anything. This turns real denials into precise role updates instead of guessing at permissions up front.

System roles are not offered from the challenge shortcut; assign Admin from the Members page instead. Challenges recorded before selectors were captured cannot be resolved this way and can only be dismissed.

Used by

• MCP servers, whose Access page writes the same grant rows as the role editor
• MCP Sessions and Authorization Servers
• Agent Sessions, where chat:read governs transcript access
• Guardrails, Risk Events, and Watchdog
• The Platform MCP, whose tools run under the caller’s roles

Further reading

• Govern agent actions with enterprise identity walks the full authorization path from the identity provider to a single MCP tool call, including grant and selector examples.
• The blog post From your IdP to a tool call: how agent authorization works covers the same path with product context.