> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.rightbrain.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.rightbrain.ai/_mcp/server.

# Connections

> Connections give Rightbrain agents and tasks external reach — native Integrations with per-principal OAuth credentials, and MCP servers connected as a client.

**Connections** is the umbrella for everything that gives an [agent](/docs/concepts/agents) — or a [Task](/docs/concepts/tasks) — reach beyond Rightbrain. There are two kinds:

* **Integrations** — native connectors to services like Gmail, Slack, HubSpot, Salesforce, and Google Sheets.
* **MCP servers** — external [Model Context Protocol](/docs/interop/mcp) servers your agent connects to as a client.

Both expose tools an agent revision can call — and both can attach at the [task level](/docs/concepts/tasks#task-level-connections) too. The difference is who builds the connection and who handles the credentials:

|                 | You provide                       | Rightbrain provides            | Auth                        |
| --------------- | --------------------------------- | ------------------------------ | --------------------------- |
| **Integration** | nothing — you pick from a catalog | the connector and its tools    | managed OAuth               |
| **MCP server**  | the server URL and its auth       | the client that connects to it | OAuth or API key you supply |

With an MCP server you bring the server; with an Integration the platform handles everything. ([Skills](/docs/concepts/skills) are a third thing an agent uses, but they're declarative guidance the model reads, not callable tools — see the [calculator-versus-mathematics](/docs/concepts/skills) distinction.)

## When to use each

* Use an **Integration** when Rightbrain has a native connector for the service — you get a curated catalog, per-tool controls, and managed OAuth.
* Use an **MCP server** when you want to connect to any MCP-compatible server, including your own, and pull in whatever tools it advertises.

## Integrations

A native Integration is a service connection plus its credentials.

* **Catalog** — browse available providers, then add the one you need.
* **Tools** — each Integration exposes individual callable tools (each with its own name, description, and input schema). You restrict which of them an agent may call with `allowed_tool_ids` — a Google Sheets connection, for example, exposes around 17 tools, and you might attach only the six an agent actually needs. Expose the minimum.
* **Connection scope** — a provider can support a user-owned connection (`user`), a shared connection (`project_default`), or both.
* **Credential policy** — each Task or agent binding declares which connection to use:

  * `invoker` resolves the connection owned by the user who caused the run.
  * `project_default` resolves the shared project connection.
  * `fixed_connection` is a runtime policy for an existing fixed user connection; it cannot be selected when authoring a new binding.

  Credentials are encrypted at rest and are never shared across projects.
* **Auth lifecycle** — an Integration connection has an `auth_state` of `connected`, `reauth_required`, or `disconnected`. Expired access tokens remain connected when refresh succeeds; failed refresh or revoked credentials can require reauthorization. Keyless MCP servers use `none` instead. Read connection state before a run so authorization failures do not surface as unexpected tool errors.

Integrations attach directly to [Tasks](/docs/concepts/tasks) and [agent](/docs/concepts/agents) revisions.

The integration catalog returns each provider's supported `connection_scopes` and authorable `credential_policies`. Providers differ: Gmail uses the invoking user's connection, Slack, Teams, and Xero use a shared project connection, and supported Google Workspace providers can offer both.

Connection administration is scoped separately. A user can authorize, inspect, and disconnect their own `user` connection with view access. Managing a `project_default` connection requires project edit access.

### Actor, binding, and principal

Three identities determine who is accountable and which connected account a tool uses:

* The run **actor** is the trusted user authority that caused the run. It can come from a user session, API key, trigger owner, or another recorded execution source.
* The Integration **binding** is revisioned configuration. Its `credential_policy` selects `invoker` or `project_default`.
* The tool-call **principal** is the connected account resolved from that policy when the Integration tool executes.

The actor and principal are not necessarily the same. One run can use the invoking user's account for one Integration and a shared project account for another. The agent may choose among the tools available to it, but it cannot choose an identity outside the binding policy.

`allowed_tool_ids` and `credential_policy` answer different questions: the allowlist controls **what** the agent may call; the policy controls **whose connection** executes the call. Run records preserve the actor basis, execution surface, and Integration `principal_type`; they do not expose the connected-account identifier. See [Observability & audit](/docs/production/observability#run-actor-and-execution-source).

## MCP servers

An MCP server connection is **outbound** — Rightbrain acts as the MCP *client*.

* **Catalog** — connect from a catalog of MCP servers (by slug) or add your own.
* **Auth** — OAuth (authorize, callback, refresh, reauthorize) or an API key.
* **Tool discovery** — after connecting, Rightbrain discovers the tools the server advertises; you choose which the agent may call.

When you connect an OAuth MCP server, Rightbrain manages the token lifecycle for you — you never handle the provider's API token directly. Attaching Notion's MCP server, for instance, discovers its full tool set (search, fetch, create pages, update pages, create databases, comments, and so on — around eight tools); you attach the whole server and let the agent pick the tools it needs per run, or narrow it with `allowed_tool_ids`.

### Direct vs Task-bound MCP

There are two ways to put an MCP tool in front of an agent, and they cost differently:

* **Direct MCP** — the MCP server is attached to the agent, so the agent's model calls the tool itself. One hop. Use this for raw data retrieval, where the tool's return value is the value.
* **Task-bound MCP** — the MCP tool is wired into a [Task](/docs/concepts/tasks), which the agent calls as a tool. Two hops: the agent's model calls the Task, and the Task's model calls the MCP server. Use this when the LLM processing *inside* the Task — extraction, transformation, a stable typed contract — is the point.

Reach for direct MCP when you want the data; reach for a Task-bound MCP tool when you want the data shaped.

```mermaid
flowchart LR
  subgraph direct["Direct MCP — one hop"]
    A1["Agent's model"] -- "tool call" --> M1["MCP server"]
  end
  subgraph bound["Task-bound MCP — two hops"]
    A2["Agent's model"] -- "task tool" --> T2["Task's model"] -- "MCP tool" --> M2["MCP server"]
    T2 -. "typed output" .-> A2
  end
```

### Two MCP directions — don't conflate them

> **Note**
>
> **Connecting to** an MCP server (this page) means your agent calls tools on an external server. That's different from **exposing Rightbrain as** an MCP server, where other MCP clients call your Rightbrain Tasks. For the second direction, see [MCP interop](/docs/interop/mcp).

## Minimal example

Add an Integration, start its OAuth flow, then check the connection state.

**`Browse the integration catalog`**

```bash title="Browse the integration catalog"
curl https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/integration/catalog \
  -H "Authorization: Bearer $RB_TOKEN"
```

**`Start authorization`**

```bash title="Start authorization"
curl -X POST https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/integration/{integration_id}/connections/{connection_scope}/authorize \
  -H "Authorization: Bearer $RB_TOKEN"
```

> **Note**
>
> Integration authorization responds with an HTTP `303` or `307` redirect, depending on the provider flow. MCP authorization responds with `303` or `307`. The target is in the `Location` header; open it in a browser.

**`Check auth state`**

```bash title="Check auth state"
curl https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/integration/{integration_id}/connections/{connection_scope} \
  -H "Authorization: Bearer $RB_TOKEN"
```

## Related

#### [Agents](/docs/concepts/agents)

Attach Integrations and MCP servers to a revision.

#### [Skills](/docs/concepts/skills)

Skills auto-provision the connections they need.

#### [MCP interop](/docs/interop/mcp)

Exposing Rightbrain as an MCP server.

#### [API Reference — Connections](/api-reference/api-reference/connections)

Integrations and MCP server endpoints.