# Connections

Sign in to a tool or MCP server once, then name it on any run. Skills and resources come in by URL the same way.

A **connection** is a tool the agent can use as you: an MCP server, or a built-in connector such
as Google or Slack. You sign in once. After that a run names the connection in `connections` and
the agent gets it, and nothing you did not name.

Connections are personal. They belong to the person who signed in, and a run started with an API
key uses the connections of the admin who created the key.

_Figure: sign in once, on the page at /docs/concepts/connections._
## Sign in once

In the console, open **Settings → Integrations**. Or, from the API, `POST /me/connections`:

```json
{"type": "mcp", "name": "deepwiki", "url": "https://mcp.deepwiki.com/mcp", "auth": {"mode": "none"}}
```

`auth` takes one of three modes:

| `auth.mode` | For |
| --- | --- |
| `bearer` | A server that takes a token: `{"mode": "bearer", "token": "…"}`. |
| `none` | A server with no auth. Refused `422 token_rejected` if it asks for one. |
| `oauth` | A server that signs in. The answer is `202` with an `authorize_url`. |

Leave `auth` out and Rush probes the server: no auth if it answers, sign-in otherwise.

A sign-in finishes in a browser. Open `authorize_url` while signed in to the console as the same
person; a browser with no session, or someone else's, cannot finish it, so a leaked link connects
nothing. Until then the connection reads `pending`; poll `GET /me/connections/{id}` for
`connected`. A sign-in not finished within 10 minutes fails with `connection_expired`.

Every connection reads back as `{id, type, name, url?, auth: {mode}, status, tools}`. A token
never comes back. `status` is `connected`, `pending` or `needs_reauth` (sign in again).

## Built-in connectors

- **GitHub** is a GitHub App you install in **Settings → Integrations → GitHub**. It is how a run
  clones a repository and opens a pull request. [`GET /o/{org}/github`](/docs/api/get-github-connection)
  lists the repositories it can reach.
- **Google**, **Microsoft** and **Slack** connect with `{"type": "app", "name": "google"}` and the
  same sign-in. A run can name them. Slack reaches the agent as the `slack` CLI signed in as you.
- **Linear** connects the same way. Rush uses it to read a Linear issue you pass in `resources`,
  and to run [Linear triggers](/docs/concepts/automations).

[`GET /o/{org}/agents/available`](/docs/api/get-agents-available) lists the remote MCP servers in
`mcp_servers`, each with the `url` to connect.

## Name a connection on a run

Each entry in `connections` takes one of three forms:

```json
{"harness": "claude", "input": "Research the bug and propose a fix.",
 "connections": [
   "6f1c2a9e-3b7d-4e0a-9c55-2d8e1f4a7b30",
   "deepwiki",
   {"url": "https://mcp.exa.ai/mcp", "auth": {"mode": "bearer", "token": "<exa key>"}}
 ]}
```

1. **An id** from `GET /me/connections`.
2. **A name**: what you named an MCP server, or a built-in connector's provider (`"google"`). Only
   your own connections match. A name two of them share is `422 CONNECTION_AMBIGUOUS`, which lists
   their ids; send one instead.
3. **An inline MCP server** `{url, name?, auth?}`, for this run and its follow-ups only. It is never
   saved to `/me/connections`. The host must resolve to public addresses
   (`422 MCP_SERVER_URL_INVALID`), and the token is stored encrypted and never returned.

An id or name that is unknown or still connecting is `422 CONNECTION_NOT_READY`. Follow-ups keep
all three. A run can name up to 20.

Secrets are not connections. They belong to a Project and reach every session in it; see
[Projects and secrets](/docs/concepts/projects).

## Skills by URL

`skills` loads up to 10 skills into the agent, each a public URL: a GitHub `tree` URL to a
directory with `SKILL.md`, a `SKILL.md` file, a GitHub repository archive, or a `.zip`. Rush fetches
each when the run is created and pins a GitHub source to its commit. A URL that cannot be fetched
is `422 SKILL_FETCH_FAILED`; no `SKILL.md`, or skills past 96 KiB, is `422 SKILL_INVALID`.

## Resources by URL

`resources` puts work in front of the agent before it starts, up to 10 entries:

- `https://github.com/<owner>/<repo>` clones the repository; `…/tree/<branch>` at a branch;
  `…/pull/<n>` on an open pull request's branch. One repository per run.
- `https://linear.app/<workspace>/issue/<ID>` puts the issue in the prompt, read through your Linear
  connection.

Any other URL is `422 RESOURCE_UNSUPPORTED`. A repository no installation of yours covers, or an
issue with no Linear connection, is `422 RESOURCE_NOT_ACCESSIBLE`.