# Scopes

> Every permission an integration token or connected app can hold, what it includes, which are privileged, and which MCP tools each one allows.

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](https://docs.sanda-os.com.au/mcp/permissions). Every tool is in the [MCP tool reference](https://docs.sanda-os.com.au/mcp/tools).

## Every scope


### fluid:read

<p class="dx-chips"><span class="dx-chip is-read">Any member may grant it</span></p>

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

Tools: [`search_fluid`](https://docs.sanda-os.com.au/mcp/tools#search-fluid), [`describe_table`](https://docs.sanda-os.com.au/mcp/tools#describe-table), [`search_docs`](https://docs.sanda-os.com.au/mcp/tools#search-docs).

### query:run

<p class="dx-chips"><span class="dx-chip is-read">Any member may grant it</span></p>

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

Includes `fluid:read`.

Tools: [`run_query`](https://docs.sanda-os.com.au/mcp/tools#run-query), [`search_documents`](https://docs.sanda-os.com.au/mcp/tools#search-documents).

### sql:run

<p class="dx-chips"><span class="dx-chip is-danger">Privileged: owners and admins grant it</span></p>

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

Includes `fluid:read`, `query:run`.

Tools: [`run_sql`](https://docs.sanda-os.com.au/mcp/tools#run-sql).

### fluid:write

<p class="dx-chips"><span class="dx-chip is-danger">Privileged: owners and admins grant it</span></p>

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`](https://docs.sanda-os.com.au/mcp/tools#list-warehouse-tables), [`import_tables`](https://docs.sanda-os.com.au/mcp/tools#import-tables), [`set_table_kind`](https://docs.sanda-os.com.au/mcp/tools#set-table-kind), [`retire_tables`](https://docs.sanda-os.com.au/mcp/tools#retire-tables), [`define`](https://docs.sanda-os.com.au/mcp/tools#define), [`list_proposals`](https://docs.sanda-os.com.au/mcp/tools#list-proposals), [`review_proposal`](https://docs.sanda-os.com.au/mcp/tools#review-proposal), [`delete_definition`](https://docs.sanda-os.com.au/mcp/tools#delete-definition).

### workspace:read

<p class="dx-chips"><span class="dx-chip is-read">Any member may grant it</span></p>

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

Tools: [`list_connections`](https://docs.sanda-os.com.au/mcp/tools#list-connections), [`connection_status`](https://docs.sanda-os.com.au/mcp/tools#connection-status), [`list_warehouses`](https://docs.sanda-os.com.au/mcp/tools#list-warehouses).

### workspace:manage

<p class="dx-chips"><span class="dx-chip is-danger">Privileged: owners and admins grant it</span></p>

Start a sync on a connection.

Includes `workspace:read`.

Tools: [`sync_now`](https://docs.sanda-os.com.au/mcp/tools#sync-now).

### warehouse:write

<p class="dx-chips"><span class="dx-chip is-danger">Privileged: owners and admins grant it</span></p>

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`](https://docs.sanda-os.com.au/mcp/tools#load-rows), [`set_intake`](https://docs.sanda-os.com.au/mcp/tools#set-intake).

### warehouse:model

<p class="dx-chips"><span class="dx-chip is-danger">Privileged: owners and admins grant it</span></p>

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`](https://docs.sanda-os.com.au/mcp/tools#list-sources), [`list_views`](https://docs.sanda-os.com.au/mcp/tools#list-views), [`create_view`](https://docs.sanda-os.com.au/mcp/tools#create-view), [`refresh_view`](https://docs.sanda-os.com.au/mcp/tools#refresh-view), [`drop_view`](https://docs.sanda-os.com.au/mcp/tools#drop-view), [`create_procedure`](https://docs.sanda-os.com.au/mcp/tools#create-procedure), [`call_procedure`](https://docs.sanda-os.com.au/mcp/tools#call-procedure), [`warehouse_advice`](https://docs.sanda-os.com.au/mcp/tools#warehouse-advice), [`optimise_warehouse`](https://docs.sanda-os.com.au/mcp/tools#optimise-warehouse), [`list_schedules`](https://docs.sanda-os.com.au/mcp/tools#list-schedules), [`create_schedule`](https://docs.sanda-os.com.au/mcp/tools#create-schedule), [`run_now`](https://docs.sanda-os.com.au/mcp/tools#run-now), [`pause_schedule`](https://docs.sanda-os.com.au/mcp/tools#pause-schedule), [`run_history`](https://docs.sanda-os.com.au/mcp/tools#run-history).

### search:manage

<p class="dx-chips"><span class="dx-chip is-danger">Privileged: owners and admins grant it</span></p>

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`](https://docs.sanda-os.com.au/mcp/tools#list-search-services), [`describe_search_service`](https://docs.sanda-os.com.au/mcp/tools#describe-search-service), [`estimate_search_build`](https://docs.sanda-os.com.au/mcp/tools#estimate-search-build), [`create_search_service`](https://docs.sanda-os.com.au/mcp/tools#create-search-service), [`update_search_service`](https://docs.sanda-os.com.au/mcp/tools#update-search-service), [`build_search_service`](https://docs.sanda-os.com.au/mcp/tools#build-search-service), [`run_search_build`](https://docs.sanda-os.com.au/mcp/tools#run-search-build), [`drop_search_service`](https://docs.sanda-os.com.au/mcp/tools#drop-search-service).

### sql:write

<p class="dx-chips"><span class="dx-chip is-danger">Privileged: owners and admins grant it</span></p>

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`](https://docs.sanda-os.com.au/mcp/tools#execute-sql).

### warehouse:append

<p class="dx-chips"><span class="dx-chip is-read">Any member may grant it</span></p>

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`](https://docs.sanda-os.com.au/mcp/tools#append-rows).

### reports:deliver

<p class="dx-chips"><span class="dx-chip is-danger">Privileged: owners and admins grant it</span></p>

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`](https://docs.sanda-os.com.au/mcp/tools#list-deliveries), [`create_delivery`](https://docs.sanda-os.com.au/mcp/tools#create-delivery), [`update_delivery`](https://docs.sanda-os.com.au/mcp/tools#update-delivery), [`send_delivery`](https://docs.sanda-os.com.au/mcp/tools#send-delivery), [`pause_delivery`](https://docs.sanda-os.com.au/mcp/tools#pause-delivery), [`delete_delivery`](https://docs.sanda-os.com.au/mcp/tools#delete-delivery).



## How scopes combine

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

| Scope | Also includes |
|---|---|
| `fluid:read` | Nothing else |
| `query:run` | `fluid:read` |
| `sql:run` | `query:run`, `fluid:read` |
| `sql:write` | `sql:run`, `query:run`, `fluid:read`, `workspace:read` |
| `fluid:write` | `fluid:read` |
| `workspace:read` | Nothing else |
| `workspace:manage` | `workspace:read` |
| `warehouse:write` | `workspace:read` |
| `warehouse:model` | `workspace:read` |
| `search:manage` | `workspace:read` |
| `warehouse:append` | `fluid:read` |
| `reports:deliver` | Nothing else |

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

| Where | How |
|---|---|
| A connected app | The person ticks scopes on the consent screen. See [connect Claude](https://docs.sanda-os.com.au/mcp/connect-claude#the-consent-screen) |
| An integration token | An owner or admin turns on switches when creating it. **May run its own SQL** is `sql:run`, and so on. Every token also holds `query:run`. See [agent tokens](https://docs.sanda-os.com.au/mcp/agent-tokens#the-switches) |
| A client that asks | A client names scopes in the `scope` parameter of its authorization request. Scopes sanda does not have are dropped. See [connect other MCP clients](https://docs.sanda-os.com.au/mcp/connect-other-clients#send-the-person-to-the-consent-screen) |

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.

:::note
A workspace that has been closed is read-only. Every credential is limited to `query:run` and `workspace:read`, whatever else it was granted.
:::