MCP: Collections and operations - Brein

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

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).

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.

Collections — the operational model.
Operate a Collection — the workflow.
CLI: Collections and API: Collections — equivalent surfaces.
MCP & OAuth — setup, authentication, and scopes.