# Connections

> The services plutonium.io reaches as you — connect one with an API key or a sign-in, see how each stands, pause or remove it

A **connection** lets plutonium.io reach another service as you. You make one on the
**Connections** page in the console. **A connection is not a permission**: it says plutonium.io
*can* reach the service, and a run *may* use that reach only with a grant that names it (see
[Permissions and trust](/docs/guide/permissions-and-trust.md)).

Each connection shows how it stands: **Connected**, **Needs attention** (with the reason, such as an
expired sign-in), **Paused** or **Removed**, with the account it reaches, the access you allowed and
who holds its secret.

**With an API key.** Press **Connect a service**, name the service and the connection, and paste the
key. The key is stored as an encrypted secret and no page ever shows it again.

**Google.** Press **Connect Google**. Google asks you to sign in and to allow **read** access to
Gmail, Google Calendar and Google Drive. You come back to the Connections page, and the connection
shows as **Connected**, with the Google account it reaches and the access you allowed. If you untick
an access on Google's screen, the connection holds only what you allowed. plutonium.io keeps the
Google credential in a store that the tools never read.

**Slack, Notion and Linear.** Under **Add a connection**, the Connections page lists every service
plutonium.io can connect with a sign-in, each with what it asks for in plain words; **Find a service**
narrows the list. Press **Connect** and the service's name beside one, such as **Connect Slack**: the service
asks you to sign in and to allow that access, and you come back to the Connections page with the
connection **Connected**. A service that shows **Not set up here yet** offers no button (see
[A service that is not set up](#a-service-that-is-not-set-up)). To connect a second account of a service you have connected,
give the new connection a name when the page asks for one (it suggests `slack_2`). A name uses
lowercase letters, digits and `_` only.

- **Slack** asks to see the public channels in your workspace and to read their messages. Your
  workspace's admin may need to approve the app first.
- **Notion** asks you to choose, on its own screen, the pages and databases to share.
  plutonium.io reaches only what you chose.
- **Linear** asks to read your issues, projects and comments.

No tool uses a Slack, Notion or Linear connection yet: each gets its tools in a later release.

**Another service (a custom provider).** An owner of the account can add a service that offers an
OAuth 2.0 sign-in and is not in the list. Under **Add a connection**, **Another service, with your
own app**, press **Add a service** and type the service's name. The page shows the redirect address
for it (`https://<your console>/api/connections/oauth/custom-<name>/callback`) with **Copy**:
register an app at the service with that address first. Then give the service's sign-in page
address, its token address, what to ask it for, and the app's client ID and secret. For a service
that publishes OpenID Connect discovery, type its sign-in settings address and press **Fill in**:
it fills most of these, and you check them before you press **Add the service**. A refused address
is named under its own field. The service then shows in the list with the others, and anyone in the
account connects to it the same way.

- **Only an owner adds one, and an agent cannot propose one.** plutonium.io sends the app's secret
  and your sign-in to the token address, so only a person types it.
- **Every address must start with `https://` and reach the public internet.** An address on a private
  network, on this machine or on a cloud metadata service is refused, when it is saved and again each
  time plutonium.io sends it a code or a token, and the refusal names the address that is wrong.
- **The secret is never shown again.** To change a custom provider, remove it and add it again.
  plutonium.io removes one only when no connection uses it, so remove its connections first.

**What reads a Google connection.** The **Researcher** agent has two Google tools: one lists your newest Gmail
messages (the sender, date and subject of each, 5 unless you ask for more), and one lists one day's
events on your primary calendar (today in the calendar's own time zone, unless you name a day).
The first time a run uses one, a card asks you to grant it the connection. A separate reader
reads the messages and events, so text inside an email or an invitation cannot direct the agent.
**Coming:** a tool that reads your Drive files.

While plutonium.io is in Google's **test mode**:

- **Only named test accounts can connect.** Another account sees an error from Google. Ask the
  plutonium.io team to add your account.
- **Google shows "Google hasn't verified this app".** Press **Continue** to go on.
- **A connection lasts 7 days.** After that Google stops it, and the first run that uses it
  shows the connection as **Needs attention**. Press **Connect Google** again: the new consent
  replaces it.

**Removing a connection.** Press **Remove**. plutonium.io deletes the stored credential; for a
sign-in connection it first asks the service to revoke the access, and removes the connection even
if the service does not answer. Notion offers no way to revoke, so remove plutonium.io from your
Notion integrations too. A connection whose secret plutonium.io held leaves the page, and so does an MCP server that
needed no sign-in, because no credential is left anywhere; one held elsewhere stays listed as
**Removed**, naming who still holds it. plutonium.io keeps the record for 30 days, so a run that names it is told you
removed it, rather than that it never existed. To connect Google again, press **Connect Google**:
the new consent replaces the removed connection.

**Pausing a connection.** Press **Pause** to stop every run from using it without removing it, and
**Turn on** to let runs use it again.

## An MCP server

An MCP server runs tools for plutonium.io's agents at another service. Under **Add a connection**,
**An MCP server** lists the servers in the official MCP Registry that plutonium.io can connect, and
**Find an MCP server** searches them. Press **Connect** beside a server: a server that needs a
sign-in asks you to sign in, and you come back to the Connections page with the connection
**Connected**. A public server that needs no sign-in connects at once, and plutonium.io holds no
credential for it. A server you have connected shows **Connected** in the list.

For a server the registry does not list, paste its address under **Or paste its address** and press
**Connect**. The address starts with `https://` and is the server's MCP endpoint (it often ends in
`/mcp`), not its website.

If plutonium.io cannot connect a server, the Connections page says why and what to change. A
connected server's card shows its name, its address and how many of its tools you approved.

**Approve its tools.** A run may call only a tool you approve. Press **Review tools** on the
server's card: it says whose account the calls act as, and lists each tool with the server's own
description, word for word, and what it asks for (**Show the schema** has the exact form). A tool
the server marks as only reading can be approved to **Read** or to **Write**; any other tool is
approved as able to write. Press **Approve**. If the server changed the tool while you read it, the
card says so and shows it again. **Stop it** takes an approval back.

When the server changes a tool you approved, that tool stops: the card says **1 tool changed: it
stops until you approve it again**, and **Review tools** shows what changed. Press **Approve again**
or **Stop it**. A tool the server no longer lists says so. **Look again** asks the server for its
tools now. On **Tools**, an approved tool shows with the others; you change it here, on
Connections. Removing the server's connection stops every tool you approved on it: if you connect
it again, you approve each tool again.

**Use an approved tool in a loop.** Name it in the loop's tools, as any installed tool, by the
name **Tools** shows (the connection's id, two underscores, and the tool's name). Its agent's role
must allow reading connections (or writing them, for a tool approved as able to write), and the
run's grant names this connection. Of the platform's roles, `general` (the agent a person talks
with) and `web_reader` (the `researcher` agent's) allow reading connections. A tool its server
does not mark read-only is approved as able to write, and one agent may not read your records or
the web and also change things in a service. So on **Tools**, **Let another loop use it** gives a
loop whose agent may not write a helper, the **Service writer**: your loop's own agent hands it
each call, it reads nothing but what it was handed, and you choose who approves each call (you,
or the person in the chat; only you, for a loop strangers open). Each call reaches the server
through the connection, and is
refused while the server describes the tool differently from what you approved. What the tool
answers is never trusted: plutonium.io reads it apart from the agent first, as it reads a web
page.

## A service that is not set up

A service that shows **Not set up here yet** cannot connect with a sign-in here yet, and the page
says *"Connecting Slack is not available here yet."* Reactor connects to a service through an
app registered with that service, once for every account, and nothing you do on the Connections
page changes that. When the app is registered, **Connect** appears beside the service. Until then,
connect the service with an API key if it gives you one.
