Scopes

A scope is one permission on an integration token or a connected app. sanda checks the scopes on every call to the MCP server, and a tool that a credential's scopes do not reach is left off its tool list.

There are twelve scopes. The list below gives each one's consent-screen wording, what it includes and the tools it allows. After it comes what to know before you grant one. Who can grant each scope, and how risky actions can wait for a person, is in permissions and approvals. Every tool is in the MCP tool reference.

Every scope

fluid:read

Any member may grant it

Read what your workspace has modelled: its metrics, dimensions, named filters and the tables sanda may query.

Tools: search_fluid, describe_table, search_docs.

query:run

Any member may grant it

Ask questions of your data, composed from the definitions your workspace agreed on.

Includes fluid:read.

Tools: run_query, search_documents.

sql:run

Privileged: owners and admins grant it

Write and run its own read-only SQL against the tables sanda may query.

Includes fluid:read, query:run.

Tools: run_sql.

fluid:write

Privileged: owners and admins grant it

Change what your workspace has modelled: put warehouse tables on the map, define metrics, dimensions, filters and relationships, and accept or remove proposals. Definitions it writes go live immediately.

Includes fluid:read.

Tools: list_warehouse_tables, import_tables, set_table_kind, retire_tables, define, list_proposals, review_proposal, delete_definition.

workspace:read

Any member may grant it

See your connections and warehouses: what is connected, when it last synced, how full the warehouse is. Never a credential.

Tools: list_connections, connection_status, list_warehouses.

workspace:manage

Privileged: owners and admins grant it

Start a sync on a connection.

Includes workspace:read.

Tools: sync_now.

warehouse:write

Privileged: owners and admins grant it

Load tables of its own rows into your warehouse (as raw.csv__…), through the same loader and storage ceiling a sync uses. It cannot touch tables a sync landed.

Includes workspace:read.

Tools: load_rows, set_intake.

warehouse:model

Privileged: owners and admins grant it

Define views, materialized views and procedures in your warehouse (as derived.…), rebuild and run them, and put a view on the semantic map. Every build runs on your compute and is billed to you.

Includes workspace:read.

Tools: list_sources, list_views, create_view, refresh_view, drop_view, create_procedure, call_procedure, warehouse_advice, optimise_warehouse, list_schedules, create_schedule, run_now, pause_schedule, run_history.

search:manage

Privileged: owners and admins grant it

Define, rebuild and remove search services over the tables on your map. The text of the columns a service names is sent to an embedding model outside Australia to be indexed, and keeping one fresh costs tokens, storage and compute, billed to you.

Includes workspace:read.

Tools: list_search_services, describe_search_service, estimate_search_build, create_search_service, update_search_service, build_search_service, run_search_build, drop_search_service.

sql:write

Privileged: owners and admins grant it

Write and run its own SQL on your warehouse and commit it: insert, update and delete rows and create tables in the derived schema, reading every landing table on the way. It runs as the same hand the SQL shell lends an owner, there is no undo, and every statement is recorded in your audit trail.

Includes fluid:read, query:run, sql:run, workspace:read.

Tools: execute_sql.

warehouse:append

Any member may grant it

Add rows to the tables an owner or admin has opened for intake, matching their columns, and nothing else: it cannot create, replace or delete a table, and it cannot change what is modelled. Any member may grant this, because which tables are open is decided by the people who run the workspace.

Includes fluid:read.

Tools: append_rows.

reports:deliver

Privileged: owners and admins grant it

Email your reports on a schedule to the addresses it names, change or pause those deliveries, and send one now. Each delivery puts a copy of the report's numbers in someone's inbox, which cannot be recalled.

Tools: list_deliveries, create_delivery, update_delivery, send_delivery, pause_delivery, delete_delivery.

How scopes combine

A wider scope includes the narrower ones it depends on, so a credential never needs to hold both.

Nothing else nests. In particular:

• sql:write is never implied by sql:run, fluid:write, warehouse:write or warehouse:model. Reading through the read-only role and committing through the builder role are different kinds of trust.
• warehouse:append never implies warehouse:write, and it does not imply query:run.
• reports:deliver does not include query:run, because sending a report is not the same as asking its questions.

Privileged scopes

Eight scopes change something or reach beyond the fluid, and only an owner or admin can grant them:

sql:run, sql:write, fluid:write, workspace:manage, warehouse:write, warehouse:model, search:manage and reports:deliver.

The other four (fluid:read, query:run, workspace:read and warehouse:append) can be granted by any member.

On the consent screen, a member sees the privileged scopes greyed out, and they are left out of the grant. Only an owner or admin can create an integration token at all. A privileged scope also lasts only as long as the person who granted it is still an owner or admin.

What to know before you grant one

Asking questions and running SQL

• fluid:read is what sanda offers a client that asks for no scope. It is ticked by default on the consent screen.
• query:run is held by every integration token, and the Excel and Power BI feed needs it. It includes search_documents on Standard and Enterprise, so searching an existing sanda search service needs nothing more. An MCP call returns at most 50 rows.
• sql:run allows one read-only SELECT, through the same read-only role as every question, returning at most 50 rows and stopping after 20 seconds. The assistant must say why it could not use run_query. A column whose name looks like a password or an identity number is refused.
• sql:write allows one statement per call, run as the warehouse's builder role. The builder reads landing tables, the derived schema and the mapping tables, and writes only in the derived schema. A sync's landing tables, a published mapping view, the search indexes and sanda's own bookkeeping are out of reach whatever the statement says. Every statement is recorded with its reason, and a write-mode statement can be held for an owner or admin to approve. It includes workspace:read because a statement has to name a warehouse.

Seeing and driving the workspace

• workspace:read never returns a credential or a connection string. Five other scopes include it.
• workspace:manage starts a sync. A sync reads from the source system and costs compute like any other.

Changing the semantic fluid

• fluid:write makes definitions live at once, not proposals, which is why only an owner or admin can grant it. Every call runs the same handler as the console's own button, with the same validation and audit record. Approvals do not hold these tools. If you want a person to make every change, leave this scope off.

Loading and shaping warehouse data

• warehouse:write lands tables as raw.csv__<name>, up to 10,000 rows and 250 columns per call, and it cannot touch a table a sync landed. It also opens a table for intake.
• warehouse:append is the one write any member may grant. It starts unticked on the consent screen. It allows appending up to 10,000 rows per call to a table that is open, and nothing else. An owner or admin opens a table for intake when they upload a CSV, or with load_rows or set_intake, and closes it in the Intake tables panel of Settings · Integrations. It includes fluid:read so that the assistant can describe the table it adds to.
• warehouse:model builds in the derived schema, which the builder role can write and nothing else. Every build runs on your compute and is billed to you, and drop_view can be held for approval.

Search and reports

• search:manage is part of sanda search, so it applies on Standard and Enterprise. A workspace owner must switch sanda search on in the console first, and an agent holding this scope cannot do that. drop_search_service can be held for approval.
• reports:deliver is email only, to at most 25 recipients within the recipient domains your workspace allows, on a schedule that falls on the quarter hour. create_delivery and update_delivery can be held for approval when a recipient is outside the email domains your members use.

action_status is offered to a credential holding sql:write, warehouse:model, search:manage or reports:deliver, because those are the scopes whose tools can be held.

Where scopes are set

An OAuth client that gets a tool refused with insufficient_scope has learned which scope it lacks, and can ask the person to approve it. An integration token cannot ask: an owner or admin turns the switch on, or creates a new token.