Connections

Connections is the umbrella for everything that gives an agent 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. 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.

• Credentials (per principal) — this is the important part. Credentials are held per principal, not per project globally:

  • a project-default principal (a shared connection the whole project uses), or
  • a per-user principal (a specific user’s own credentials).

  Credentials are encrypted at rest and are never shared across projects.

• Auth lifecycle — an Integration principal has an auth_state (connected, reauth_required, or none for keyless connections). When a token expires or is revoked, the state flips to reauth_required and you re-authorize. The dashboard surfaces this so runs don’t fail silently.

Integrations attach to an agent revision and, as of July 2026, directly to Tasks as well.

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