> For the complete documentation index, see [llms.txt](https://docs.rootcause.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rootcause.ai/api-and-integrations/api-access/mcp-integration/mcp-permissions-and-safety.md).

# Permissions and Safety

## Scopes

Every connection carries permission scopes: the ones approved at the OAuth consent screen, or the ones on the API key. The tool list is filtered to match, so a read-only connection has no write tools at all. If the assistant reports it lacks a tool, that is the filter working.

The scope areas are the same as everywhere on the API page: Sources, Datasets, Ontology, Digital Twins, Simulations, Connectors, Catalog, Jobs, Exports, Agent, Reports, and Applications (see [API Access](/api-and-integrations/api-access.md#creating-an-api-key)).

Standard MCP clients request the **default bundle**: read access to your content plus the Agent scopes.

* Read scopes cover exploring, querying, and previewing, including viewing simulation results. Running a simulation (an execute action), Connectors, and Exports are not included.
* Agent scopes cover the assistant's own working surface: loading skills, building charts, searching documentation, usage queries, building and running Applications.
* Nothing in the default bundle can change your content: no editing datasets or ontology, no creating or training twins, no imports.

To grant write access, connect with an **API key** carrying the write scopes you choose. The consent screen shows a client's requested scopes as a fixed list, so a broader OAuth grant is only possible for clients built to request one.

A connection pinned to one workspace at consent refuses every other workspace, regardless of scopes.

## Confirmation gate

Tools that change ground truth, cannot be undone, or take a long time do nothing on the first call: the server replies that nothing has happened and the assistant must ask you before calling again with explicit confirmation. This gate covers:

* **Shared truth**: editing the ontology, modifying a dataset definition, updating or retiring a Digital Twin
* **Irreversible actions**: deleting a dataset or twin, publishing an Application (publishing makes it runnable outside the chat: REST endpoints, schedules, webhooks)
* **Long-running work**: training, causal discovery, external imports. External imports carry a duration hint in the confirmation; for training and causal discovery it only says a long-running job is starting, because the duration depends on the size of the data.

Reading, querying, previewing, and simulating run without ceremony. One exception: a query asked to persist its result as a dataset is gated like any other change to shared truth.

## Background jobs

Connector imports, document extraction, discovery and training return a run id immediately and complete in the background (`import_source` and `research_to_table` are awaited inline instead and answer with the finished source). The assistant polls (`check_background_runs`) and reports when the job lands. These are the same background jobs visible in the workspace UI.

## Rate limits

| Credential       | Limit                                          |
| ---------------- | ---------------------------------------------- |
| OAuth connection | 120 requests per minute                        |
| API key          | 60 per minute by default, configurable per key |

Responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`; a limited request gets `429` with `Retry-After`. Conversational use does not hit these; they stop runaway loops.

## Revoking and auditing

* **Revoke**: every authorized client is listed in **Connected Apps** on the API page. Revoking deletes the grant and its refresh tokens immediately; an already issued access token can outlive revocation by up to 15 minutes.
* **Audit**: tool failures and AI cost events land in the organisation audit log, queryable conversationally (see [What You Can Do](/api-and-integrations/api-access/mcp-integration/mcp-capabilities.md#monitor-usage)).
* **Key hygiene** (legacy method): scope narrowly, set an expiry, use the IP allowlist, rotate. See [API Access](/api-and-integrations/api-access.md#managing-keys).

{% hint style="info" %}
Keep everyday connections read-only; grant write access only to connections used for actual build work. Reading cannot break anything, and the confirmation gate protects the rest.
{% endhint %}