Agent permissions are behind the
agent-identity feature flag. On Lightdash Cloud, ask Lightdash support to turn it on for your organization. On a self-hosted instance, enable the flag.Choose what agents can do
Agent permissions are in the Permissions section of Organization settings → Agents, below Identity. Under Agent scope permissions, choose one option:
A Current badge marks the saved choice.
Read and query only does not make SQL read-only. Raw SQL runs with the warehouse permissions of the identity that agents run as, so limit writes in the warehouse. See Agent identity.
Custom scope
Custom scope shows a switch for each capability, in three groups: Read and query, Make changes, and Developer and admin. Developer and admin stays collapsed until you select it.- Each switch applies to every role. For a person with a built-in role, agents get every capability that is on, within the person’s own permissions. A capability that is off is off for every agent, whatever the person’s role, custom roles included.
- Turning off every switch turns agents off. The page says “Agents are turned off for everyone.” Agents stop working in Ask AI, the Slack agent, and MCP clients. People can still do the work themselves. Agent permissions do not apply to a personal CLI login, so the CLI keeps working. The login’s OAuth scopes still apply. With Read and query only or Custom scope, the CLI also cannot do some operations that are reserved for people. With any option, including Match the person, the CLI cannot update or delete groups, add or remove group members, update, replace or delete SCIM groups, or change the agent identity settings. Without the
agent-identityfeature flag, none of these checks apply.
Capabilities
An agent can take an action only when the person’s own permissions allow it and the capability is on. Each refusal names the capability.Operations that need several capabilities
Some operations need more than one capability. Lightdash refuses the operation unless every capability it needs is on:
An agent that changes the Git repository needs Delete content only when its change deletes or renames a file. Lightdash checks the change before it commits or pushes anything.
Refusals
When agent permissions block an action, the refusal names the capability, for example: “Your organization’s agent permissions do not allow Raw SQL. Ask an admin to change Permissions on the Agents page.” The refusal is the same when the person’s own roles do not allow the capability. An action can fail more than one check. Lightdash stops at the first check that fails, and the first line of the refusal names it. In the in-app chat and in MCP clients, the refusal then lists everything else that blocks the action:- Also needed names the other blockers, for example: “Also needed: Publish and share”. A blocker is a capability from the table above, or another limit, such as “access to agents”.
- See why links to My agent identity.
Turn off Raw SQL for agents
Raw SQL lets an agent list warehouse tables and run SQL outside the data models. An agent can use it when the person’s own permissions allow raw SQL and the limits allow Raw SQL. In the in-app chat, SQL mode must also be on, and the person needsmanage:SqlRunner. Approving SQL execution also needs manage:SqlRunner.
To turn it off for every agent, choose Custom scope, turn off Raw SQL, then review and save. Agents then get the refusal “Your organization’s agent permissions do not allow Raw SQL.”
Who can use agents
Under Who can use agents, choose:- Everyone whose role allows AI. Anyone with a role that allows AI can use agents.
- Only these groups. People must belong to at least one of the groups you choose, and their role must also allow AI.
- Choosing groups needs an Enterprise license. Group management itself is available to every organization. Without the license, the Who can use agents row is hidden. If a group limit was saved earlier, the row says “Groups are unavailable. The saved group restriction still applies.”, and Allow everyone removes the limit.
- Only these groups needs at least one group.
- When every group you chose is deleted, the page warns “No one can use agents. All chosen groups are deleted.” Choose other groups, or Everyone whose role allows AI.
manage:AiAgent scope.
manage:AiAgent also lets a person use every agent in the project, including agents kept to admins and developers or to specific users and groups. With view:AiAgent instead, a person can use agents open to everyone in the project. Anyone named in an agent’s user or group access can use that agent. Roles add up: a project-level custom role without manage:AiAgent doesn’t take it away from someone whose organization role is Developer or Admin.
Review and save
Lightdash saves the changes under Agent scope permissions and Who can use agents together. The page counts the unsaved changes, for example “4 unsaved changes”. Discard returns to the saved state.1
Select Review and save
The Review changes to agent permissions dialog opens.
2
Read the review
STOPS lists what agents can no longer do, ALLOWS lists what they can do again, and WHO says who can use agents. When every capability is off, it says “Agents are turned off for everyone”.
3
Save
Select Save changes. Back returns to the page and keeps your changes.

Agents over MCP
The Agents over MCP switch lets MCP clients use the organization’s agents and their context. It affects MCP only. Turning it off does not stop Ask AI or the Slack agent. To turn agents off everywhere, choose Custom scope and turn off every capability.- The switch saves at once. It is not part of Review and save.
- It shows only to people who can change the setting.
- For these people, Settings → MCP → General shows Enable agents over MCP with a Change on the Agents page link. It reads On or Off, or Disabled when MCP access is off.
- Allow content changes via MCP stays on Settings → MCP → General.

Custom roles
Custom roles have an Agent permissions group in the AI Features section of the role editor, with the 11 capabilities above under Read and query and Changes. The role editor labels Git repository changes (dbt) as Write to dbt. A new custom role starts with Read and discover, Query data, Export results and Raw SQL on. Custom roles keep their own agent permissions. With Read and query only or Custom scope, the organization’s choice can only narrow them. For a person with a custom role, agents get what the role allows, minus the capabilities that the organization turned off. With Match the person, Lightdash does not check a custom role’s agent permissions.
When you take agent access away
Lightdash reads agent access each time it checks a request, and does not copy the access into a token. A change applies at the next check. A request that has already passed its checks can finish. This applies when:- An admin deactivates a person.
- A person loses a role, or a custom role loses a capability. The capability stays when another role of the person still allows it.
- An admin turns off a capability, or turns off every capability.
- An admin removes a group from Who can use agents, or a person leaves every group that is allowed.
Work that is queued or running
Some agent work runs after the person asks for it. This work checks the person again when it starts, and again before it delivers or publishes. When a check refuses, the later steps do not happen. What the work has already published stays. Some Slack and Autopilot delivery steps check again only when the last passing check is at least 30 seconds old. A change made inside that window can miss the next post.
Lightdash checks only at these points. A step that has passed its check can finish, however long it takes.
What a change does not cover
- Personal access tokens and service account tokens. Agent permissions do not limit them. See Personal access tokens.
- A person’s ordinary role. When the session cache is on (
EXPERIMENTAL_CACHE=true), a change to a person’s role can take up to 30 seconds to reach a browser session or a token. The agent permission check itself reads roles each time, with no delay. - Tokens that the warehouse has issued. Lightdash does not ask the warehouse to revoke a token that the warehouse has already issued. The warehouse decides how long that token is valid. Work that already has a warehouse connection can finish.
Reserved for people
With Read and query only or Custom scope, agents can never do these operations, even with Administration on. The operations include:- Change roles, groups, and project or space access.
- Create spaces.
- Remove organization members or change their membership.
- Manage custom roles, service accounts and OAuth clients.
- Create or rotate personal access tokens, and create invite links.
- Change the agent permissions, the agent identity rules, or shared agent accounts.
- Change a project’s agent SQL scope.
- Change feature flag overrides.
- Rotate the SCIM access token.
- Get the Google Drive access token.
- Change the organization settings, including the AI settings.