MCP: Integrations and Broker

One tool covers external systems over MCP: driftless_broker. It operates a Connection that already exists, and never connects or disconnects one (setup is a human-led flow in the dashboard or CLI, not on the MCP surface). If an agent needs an operation the tool does not list, it must report the missing capability, never author a script.

The Broker is gated: off by default in production (DRIFTLESS_BROKER_ENABLED), with a separate external lane (DRIFTLESS_BROKER_ROLLOUT) and per-principal grants. A listed action is not a usable one: a faceless OAuth/MCP caller with no grant gets an empty result even against a healthy connection.

The broker tool

driftless_broker is action-based: pass action to pick the operation. Credentials resolve server-side and every call is audited. Setup (connect / disconnect) and authoring Nango scripts are separate, human-only lanes not reachable here.

Actions

Action	Purpose	Effect
`connections`	List the workspace’s Connections with health, criterion and next actions	read
`context`	The connection’s effective context: criterion resolved to trust/staleness + next action (read it BEFORE working the provider)	read
`operations`	List a provider’s operations, or search across providers	read
`capabilities`	The capability directory (kinds, effects, states, gates)	read
`inspect`	Full spec of one operation (schema, effect, risk, idempotency)	read
`invoke`	Execute one named operation inline (read or write)	read / write
`models`	Importable record models (enabled syncs)	read
`records`	Read a synced model’s records from the mirror	read
`document-content`	Read one document’s bounded, citeable text, live (any content provider)	read
`page-content`	DEPRECATED Notion-only alias of `document-content`	read
`index-preview`	Dry-run index: candidate counts and samples	read
`index`	Materialize connector documents (Driftless-owned)	admin
`import`	Import mirror records into a Collection (saved connector mapping)	write
`events`	The inbound provider event feed	read
`attach-criterion` / `detach-criterion`	Attach or remove a Knowledge criterion slug on a Connection	admin

driftless_broker action:'connections'
driftless_broker action:'capabilities' provider:'notion'   → only a `ready` capability is usable

Gates and permissions

Three independent, fail-closed gates apply to an external caller, in order: the master switch (DRIFTLESS_BROKER_ENABLED), the external lane (DRIFTLESS_BROKER_ROLLOUT), and a per-principal grant. An operation must also be policy-allowed; in production the policy registry ships empty, so no write is invokable.

Scope	Covers
`broker:read`	`connections`, `context`, `operations`, `capabilities`, `inspect`, `models`, `records`, `document-content`, `page-content`, `events`
`broker:invoke`	`invoke` (a read or write operation), `import`
`broker:admin`	`attach-criterion` / `detach-criterion`, `index-preview`, `index` (indexing curates what the workspace can retrieve/cite — connection administration, not invocation); grants are owner/admin

The broker:* scopes are enforced only when the Broker is enabled, and they gate the lane on top of rollout and grants. An internal caller (an owned API key or dashboard session) skips the grant gate but still needs the rest.

Reads and materialization

The reads differ in whether they hit the provider live and what they create. records reads the mirror/cache; document-content reads live through the provider-general documents route; index materializes Driftless-owned connector documents; import maps mirror records into Collection Records. Normal context retrieve never queries a provider — and when a retrieve query matches indexed connector documents you didn’t request, the response suggests sources:['connectors'] in next_action instead of including them.

driftless_broker action:'context' provider:'notion'                                       → read the criterion FIRST
driftless_broker action:'records' provider:'notion' model:'ContentMetadata' limit:5       → from the mirror
driftless_broker action:'document-content' provider:'notion' external_id:'<id>'           → live, bounded, cited
driftless_broker action:'import' provider:'notion' collection_id:'<uuid>'                 → mirror → Collection Records

Availability

Capability	State
`driftless_broker` tool listed	Only when `DRIFTLESS_BROKER_ENABLED` is on
Notion reads (`records`, `document-content`, `index`)	Beta, read-only
Broker writes (`invoke` a write op) in production	Not available (policy registry ships empty)
Synthesized per-workspace read tools (`driftless_<provider>_records`, `driftless_<provider>_document_content`)	Available only when synthesis is enabled and a capability is `ready`
Write-capability synthesis	Not available (never synthesized)

Integrations and Connections, Broker - the model and semantics.
Use external context in operational work - the workflow.
CLI: Integrations and Broker, API: Broker and Connections - the other surfaces.
MCP & OAuth - setup, auth, and scopes.

Get started

Connect

Concepts

Work & collaborate

Guides

Agents

MCP reference

CLI reference

API reference

Platform

MCP: Integrations and Broker

The broker tool

Actions

Gates and permissions

Reads and materialization

Availability

​The broker tool

​Actions

​Gates and permissions

​Reads and materialization

​Availability

​Related

The broker tool

Actions

Gates and permissions

Reads and materialization

Availability

Related