Skip to main content
An integration links your workspace to a system Driftless does not own: a source of records, documents, or actions that lives in someone else’s product. You connect it once, and from then on Driftless can read (and, where enabled, act) through a bounded, audited, workspace-scoped link. This page is the map of that surface: how a provider becomes a Connection, what a Connection does and does not give you, and which providers are actually operational today. The execution verbs themselves (operations, invoke, records, and the rest) live in the Broker reference.

​
What an integration is

Three words get used interchangeably and should not be:
  • Provider is the external system itself: Notion, HubSpot, GitHub. A provider is connectable only if Driftless ships a connector for it (see Provider availability). Being listed in an upstream catalog is not the same as being operational in Driftless.
  • Connection is one authorized, credential-bearing link from your workspace to a provider, stored as an integration of type nango:<provider>. This is what the Broker operates.
  • Integration is the stored link in general. Customer-facing integrations are Broker Connections (nango:<provider>).
Connecting a provider does not by itself make its data appear in context retrieve. External data is not Knowledge. It reaches retrieve only after an explicit index step and an explicit connector-source retrieve request. See Broker: reads and materialization.

​
Availability

The Broker and Connections surface is gated. It is off by default in production and turns on per environment; the external agent lane is a separate switch on top of that. Truth states used across these pages: Today the one production connector is Notion, read-only (Beta). Write operations are not exposed for any provider in production.

​
Connect a provider

Setup happens in the dashboard or the CLI, never over MCP. Connecting is a privileged, human-led flow: it establishes credentials, which Driftless never stores or sees (they live in the credential vault and are injected server-side).
In the dashboard the same flow is Settings -> Connections. Reconnecting an expired connection is a re-authorize (run connect again, or use the dashboard reconnect action). Disconnecting revokes the credential at the vault. None of these verbs exist on the MCP surface: an agent operates a connection that already exists, it never connects or disconnects one.

​
Connection status

A Connection reports one plain, server-derived status. The CLI (driftless broker connections) and dashboard render the same value.

​
Capabilities and their status

A capability is one thing a Connection can do: a sync, a record model, a read action, document content, or a (declared but disabled) write policy. The capability directory reports each one with its own status, distinct from the Connection’s: Only a capability with status ready is usable. gated and disabled are the states most easily mistaken for “available”: the capability is real and registered, but the environment or your grants keep it closed.

​
From connected to usable

A healthy OAuth Connection is the first rung, not the finish line. For an external agent to actually invoke a capability, every link in this chain must hold:
  1. Provider ships a connector in the Driftless registry (with its own rollout: internal, beta, or ga).
  2. Connection is healthy (synced).
  3. Capability has reached ready.
  4. Rollout / external lane is open: the Broker is enabled and the external OAuth/MCP lane is on.
  5. Grant exists: an owner/admin has granted the calling principal access for that provider and effect.
  6. Operation is policy-allowed.
An internal caller (a human dashboard session, or an owned API key carrying a human identity) skips the grant gate but still needs the rest. A faceless OAuth/MCP bearer with no grant sees an empty connections list, even for a perfectly healthy connection. See Broker: gates.

​
Permissions and grants

  • Setup (connect, confirm, disconnect) is a workspace-member action, done via the CLI or dashboard. It is not reachable over OAuth/MCP.
  • Reads and writes through the Broker are governed by identity and scopes for internal callers, and additionally by rollout plus grants for external (OAuth/MCP) callers.
  • A grant is a coarse authorization row: { principal, provider, effect }, with * wildcards, fail-closed (no grant means no access). Managing grants is owner/admin only and is done through the API or dashboard, not the agent surface.

​
Provider availability

Evidence-based, from the connector registry and operation policy. “Import” means mapping mirrored records into Collection Records; “Index” means materializing page content into Driftless-owned connector documents for retrieve. In production, writes are not invokable for any provider (the operation-policy registry ships empty), so every “Writes” cell below is Not available today.

​
How Driftless uses Nango

Nango is the credential vault and execution substrate behind Broker Connections. It owns the OAuth handshake, stores provider credentials encrypted, and injects them server-side per request, so a secret never reaches Driftless application code, the CLI, MCP, or a model. Driftless only ever passes a provider config key and a connection id. One consequence matters for reading this surface: the Nango catalog is Nango’s, not a Driftless availability list. A provider that Nango can technically connect is operational in Driftless only if it has an entry in the Driftless connector registry and an allowed operation policy. That is why Provider availability is shorter than any upstream catalog.