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. Today two kinds exist: Broker Connections (
nango:<provider>) and the GitHub App (github), which is a different surface with a different purpose (see Provider availability).
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:
| State | Meaning |
|---|
| Available | Shipped and usable now. |
| Beta | Shipped, usable, still stabilizing. |
| Gated | Exists but withheld unless a flag, rollout, or grant opens it. |
| Internal | Present in code for internal/staging use; not a public capability. |
| Stub | A declared placeholder with no live sync or action. |
| Not available | Not shipped as a usable capability. |
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).
driftless integration catalog # providers you can connect
driftless integration connect notion # start the authorize flow
driftless integration confirm notion # persist the connection after authorizing
driftless integration list # your connected integrations
driftless integration rm <integration-id> # disconnect (aliases: delete, disconnect)
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.
| Status | Meaning |
|---|
disconnected | No live credential; connect or reconnect. |
needs_reconnect | The credential expired or was revoked upstream. |
setup_failed | The connect flow did not finish provisioning. |
no_syncs | Connected, but no sync is configured yet. |
syncing | The first or a subsequent sync is running. |
sync_failed | The last sync failed; the error is surfaced. |
synced_empty | Synced, but nothing was shared to read (share a page/database). |
synced | Healthy: records are available. |
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:
| Capability status | Meaning |
|---|
declared / deploy_pending / deployed | Being provisioned; not usable yet. |
deploy_failed | Provisioning failed. |
sync_starting / syncing | Data is being mirrored; not ready yet. |
ready | Usable now. |
empty | Ready, but no records yet. |
needs_reconnect | Blocked on a stale credential. |
gated | Withheld by rollout or a missing grant. |
disabled | Toggled off, or a declared-but-disabled write. |
unsupported | Not offered for this provider. |
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:
- Provider ships a connector in the Driftless registry (with its own rollout: internal, beta, or ga).
- Connection is healthy (
synced).
- Capability has reached
ready.
- Rollout / external lane is open: the Broker is enabled and the external OAuth/MCP lane is on.
- Grant exists: an owner/admin has granted the calling principal access for that provider and effect.
- 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.
| Provider | Connection | Reads | Writes | Import | Index | Retrieve | Status |
|---|
| Notion | Available | Available | Not available | Available | Available | Available (after index) | Beta, read-only |
| HubSpot | Gated | Gated | Not available | Not available | Not available | Not available | Internal |
| Google Drive | Not available | Not available | Not available | Not available | Not available | Not available | Stub |
| Google Docs | Not available | Not available | Not available | Not available | Not available | Not available | Stub |
| GitHub App | Available | n/a | n/a | n/a | n/a | n/a | Available (separate surface) |
| GitHub (Broker) | Not available | Not available | Not available | Not available | Not available | Not available | Not available |
GitHub App and a GitHub Broker Connection are different surfaces. The GitHub App (type: github) observes pull requests and pushes to keep context from drifting and to feed the Auditor; it is not a Broker Connection and exposes no invoke. A GitHub Broker Connection (type: nango:github) for write operations like creating an issue is not shipped (no connector registry entry). References to GitHub operations in tool descriptions are illustrative only.
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.
