> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rerun.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Connectors

> Give an agent access to Gmail, Slack, Notion, Stripe and hundreds of other services.

A connector is a ready-made integration. Installing one on an agent gives it that service tools, plus a skill explaining how to use them, plus wherever the credentials live.

Connectors are installed **per agent**, not per Box. Two agents in the same Box can each have their own Gmail connection.

## Install one

<Tabs>
  <Tab title="From the agent panel">
    Open the **Connectors** tab, search the library, and click the connector. Rerun tells you what it needs before you commit.
  </Tab>

  <Tab title="Ask the agent">
    Name the service in the chat. The agent searches the library itself and raises a setup card for you to finish. It never asks you to paste a key into the conversation.
  </Tab>

  <Tab title="From the API">
    [`search_connectors`](/api/tools/connectors#search-connectors) then [`attach_connector`](/api/tools/connectors#attach-connector). The API declares the connector; you finish the sign-in in the app.
  </Tab>
</Tabs>

## How a connector authenticates

A service can offer several ways to connect, and you pick one at install time.

| Method      | What you do                                                                        |
| ----------- | ---------------------------------------------------------------------------------- |
| **Managed** | Click sign in. Rerun brokers the OAuth and proxies the calls. Nothing to configure |
| **OAuth**   | Sign in to the service in a browser window. Rerun stores the token on your Box     |
| **API key** | Paste a key into a masked form. It goes straight to your Box                       |
| **Command** | The connector runs a local MCP command on your Box                                 |
| **None**    | Nothing to connect. It works right away                                            |

## Statuses

Every connector on an agent shows one of three states:

<CardGroup cols={3}>
  <Card title="active" icon="circle-check">
    Connected. Its tools are available to the agent.
  </Card>

  <Card title="needs_auth" icon="circle-user">
    Waiting for you to sign in.
  </Card>

  <Card title="needs_config" icon="circle-alert">
    Waiting for a credential, or for you to pick between several ways to connect.
  </Card>
</CardGroup>

An agent with a connector in `needs_auth` or `needs_config` will tell you so rather than silently failing.

## Where credentials live

Credentials go to your Box and stay there. Rerun's database keeps only a reference to the variable name, never the value.

That holds everywhere:

* The [API](/api/tools/connectors) accepts no secret at all.
* When an agent needs a key, it opens a masked form. The value never enters the conversation, and the agent only learns which variable name was filled.
* Capturing an agent into a [template](/templates/create) ships the variable names, never the values.

<Warning>
  Never paste an API key, a password or a token into the chat. The conversation is stored and sent to the model. If an agent ever asks you to, refuse and use the masked form instead.
</Warning>

## Missing a connector

Two ways forward.

**Ask for it.** The **Connectors** tab has a request form. Requests go to the Rerun team and the library grows from them.

**Add the MCP server yourself.** Switch on expert mode, open the **MCP** tab, and register any Model Context Protocol server: HTTP, SSE or a local command, with its own headers, OAuth or environment variables. Anything with an MCP server works with Rerun today, connector or not.

Reference a stored secret in an MCP config with `${VARIABLE_NAME}`. It resolves on your Box at run time.