> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trybrein.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP: Collections and operations

> Search and configure Collections, advance typed Records, and resolve cross-collection Entities through bounded, governed MCP tools.

Collections are Driftless's operational substrate: pipelines, CRM rows, trackers, and other structured work. Their MCP tools are action-based, bounded by default, and use the same server contracts as the dashboard and CLI. Writes require `work:write`; destructive collection purge additionally requires a human owner/admin identity.

## Collections and records

Use `driftless_collection_query` for bounded reads. Before acting on a record, load the Collection's criterion with `driftless_collection action:'context'`; it returns the Knowledge that governs how the team handles those records.

| Tool                                 | Main actions                                                                                        | Purpose                                                                              |
| ------------------------------------ | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `driftless_collection`               | `search`, `list`, `get`, `add`, `update`, `archive`, `restore`, `doctor`, `context`, `presentation` | Configure and inspect a Collection; `get` is brief unless `view:'full'` is requested |
| `driftless_collection_query`         | `query`, `get`, `aggregate`                                                                         | Read bounded records with explicit projection, filtering, and continuation           |
| `driftless_collection_record`        | `add`, `update`, `history`                                                                          | Create or advance typed records; status must match the Collection lifecycle          |
| `driftless_collection_purge`         | single guarded call                                                                                 | Preview with `dry_run`, then confirm with `expected_version`; owner/admin only       |
| `driftless_collection_record_delete` | single guarded call                                                                                 | Preview and delete one record without deleting its distilled Notes                   |

```text theme={"theme":"github-light"}
driftless_collection action:'context' id:'<collection-id>'
  → { criterion: [ ... ], criterion_missing: [] }

driftless_collection_query action:'query' collection_id:'<collection-id>' limit:25
  → { status:'ok'|'continue'|'incomplete', data:[ ... ], page_info:{ ... } }
```

## Entities

An Entity is a cross-collection identity that records can reference. `driftless_entity action:'upsert'` is idempotent on `(kind, dedup_key)`.

```text theme={"theme":"github-light"}
driftless_entity action:'upsert' kind:'company' name:'Acme' dedup_key:'acme.com'
```

## Permissions

| Scope or role | Covers                                                                                |
| ------------- | ------------------------------------------------------------------------------------- |
| member read   | Collection and Record reads, criterion context, history, and doctor                   |
| `work:write`  | Create and update Collections, Records, and Entities; archive and restore Collections |
| owner/admin   | Permanent Collection purge                                                            |

MCP clients cache tool schemas per connector session. Reconnect the connector after an upgrade so removed or changed tools are reflected in the client.

## Related

* [Collections](/concepts/collections) — the operational model.
* [Operate a Collection](/guides/operate-a-collection) — the workflow.
* [CLI: Collections](/cli/collections) and [API: Collections](/api/collections) — equivalent surfaces.
* [MCP & OAuth](/mcp/overview) — setup, authentication, and scopes.