Docs

Connectors

Consumer-facing guide to how agents relate to your workspace's data connectors. Connectors are the inbound pipes — CRM, call recordings, meeting notes, comms, docs, support tickets, and tracked social accounts — that fill the warehouse every agent queries. For the full how-to on connecting a source (the catalog, the four connect methods, reconnecting a broken source, the health badge), see Connecting data sources.

The agent posture: read, never manage

Agents consume connector data and read connector state; they never connect, disconnect, reconnect, or re-attribute a source.

  • Consume: the data a connector syncs lands in the warehouse and reaches agents through the normal data tools (data.query, data.cluster_search, knowledge-base search). An agent never talks to a connector directly.
  • Read state: an agent can check what is connected and how healthy it is via the connection:// resource family — the catalog (connection://catalog), the connected instances (connection://list, connection://<id>), a lean polling status (connection://<id>/status), the recent sync-run history (connection://<id>/runs), and a per-connector data summary (connection://<id>/summary). These reads need only the connections:read scope and are available over MCP and the REST API (GET /connections...).
  • Never manage: connecting, disconnecting, reconnecting, and owner attribution are workspace configuration — they run through the console Connections page and the REST API under a human's own credentials, and are deliberately absent from every agent tool kit and from the MCP tool surface. An agent that notices a broken connection reports it (naming the connection and its health) and points a human at the console; it cannot "fix" the connection itself.

This split is structural, not advisory: the agent scope bundles carry no connections:write / connections:delete, and the connection lifecycle operations are intentionally off MCP.

What an agent should do with connection state

  • Before blaming the data: a question that comes back empty may be a source that stopped syncing. Read connection://<id>/status (or /runs) to check health before concluding the data does not exist.
  • When asked "what's connected?": read connection://list and answer in plain language — the provider names and their health, not raw rows.
  • When something is broken: say which connection needs attention (needs_reauth, error) and hand the human the console path — Settings → Connections — to reconnect it.

Related reading