# Connectors — use the user's integrations

Connector access has two gates: the builder selects which services the agent may use, and each user connects their own account. ONBF keeps OAuth credentials away from the agent.

## Two separate setup responsibilities

| Who | What they do | Effect |
| --- | --- | --- |
| **Builder** | Selects services under **Settings → Required connectors**. | Acts as the runtime allowlist. Only selected providers' tools are exposed to the agent. |
| **User** | Connects or reconnects their own account under **Connectors**. | Authorizes ONBF to use that service for this user. |

> **Selected does not mean connected:** A provider's tools can appear because the builder allowed it even when the current user has not connected it. Calls then return `connected: false` with a user-facing reconnect message.

## Security model

- The user completes OAuth on ONBF and can revoke it from their dashboard.
- ONBF stores OAuth tokens encrypted and refreshes them server-side. Your agent never receives a provider token.
- Read actions require `connectors:use`; write actions additionally require `connectors:write`.
- Connector tools are currently run-session-only and unavailable to personal access tokens.

## Recommended agent flow

1. Your agent calls `list_connections`, which is already filtered to the providers you allowed for this agent.
2. It checks `connected` and `needsReconnect` before using a provider tool.
3. If the provider is available, it calls one of the exact tool names returned in `tools`.
4. If not, it asks the user to connect or reconnect that service in their ONBF dashboard, without exposing raw provider errors.

## Who calls the connector tools

Your only setup step is choosing which services this agent may use. Whether a specific user's account is reachable is resolved at runtime, per run.

### MCP

**Nothing for you to build.** Once your platform is pointed at ONBF's MCP server, your agent already has the connector tools in its tool list and does the calling itself, mid-run, whenever it decides to. There is no per-tool setup and no code on your side — connecting happens once on the **[MCP transport](/docs/mcp)** page.

The tool list your agent sees already reflects both gates — your allowlist and this user's connected accounts — so unavailable providers simply aren't offered to it.

### HTTP API

**Your backend makes this call**, at the moment your agent decides it needs the connector tools. The run credential from the webhook is the bearer token.

Discovery is authenticated `GET /api/passport/v1/tools`; your backend then calls `list_connections` and POSTs to the returned provider tool. The catalog applies the same allowlist and scopes as MCP.

## Available connectors

| Connector | Capabilities | Access |
| --- | --- | --- |
| **[Google Drive](/docs/connectors/google-drive)** | List, search, read text and download files. | Read-only |
| **[Gmail](/docs/connectors/gmail)** | List, search, read, download attachments and create drafts. | Read + draft; never send |
| **[Google Calendar](/docs/connectors/google-calendar)** | List/search events and create/update events. | Read + write |