Connections

Connections is the umbrella for everything that gives an agent — or a Task — 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 servers your agent connects to as a client.

Both expose tools an agent revision can call — and both can attach at the task level too. The difference is who builds the connection and who handles the credentials:

With an MCP server you bring the server; with an Integration the platform handles everything. (Skills are a third thing an agent uses, but they’re declarative guidance the model reads, not callable tools — see the calculator-versus-mathematics 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 and agent 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.

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, 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.

Two MCP directions — don’t conflate them

Minimal example

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

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

Related