# Start a sign-in that connects an account or MCP server to one agent.

`POST /o/{org}/agents/{agent}/connections`

Starts the sign-in for one of the connections the agent's template names, for the user of your app the agent serves. That person needs no Rush account: send them to `authorize_url`, where they sign in to the app or the MCP server with Rush's OAuth client; the link works once and expires in 10 minutes. Then read the connection by its `id` until `status` is `connected`.

`type` is `app` for a built-in app (`outlook`, `gmail`, …) or `mcp` for an MCP server that signs in with OAuth; `name` is the name the template's connection has (`GET /o/{org}/agents/{agent}` lists them under `connections`). An MCP server is signed in to at the same address as the template's. A Gmail or Outlook connection the template names with an `access` level asks the user for that level alone. Connecting the same name again replaces the agent's earlier connection of it.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org` | path | string | yes | The org's slug or id. A caller with no role in the org gets `404`. |
| `agent` | path | string | yes | The id or name of an agent made from a template (`POST /o/{org}/agents {template, name}`). |

## Request body

- `type` (string, required, one of `app`, `mcp`)
- `name` (string, required): One of the connections the template names, e.g. `outlook` or `notion`.

## Example: example

```bash
curl -X POST "https://api.phoenix.so/o/$RUSH_ORG/agents/$AGENT/connections" \
  -H "Authorization: Bearer $RUSH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "mcp",
    "name": "notion"
  }'
```

```typescript
const org = process.env.RUSH_ORG;
const agent = process.env.AGENT;

const res = await fetch(`https://api.phoenix.so/o/${org}/agents/${agent}/connections`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RUSH_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type: "mcp",
    name: "notion",
  }),
});

console.log(res.status, await res.json());
```

```python
import os

import requests

org = os.environ["RUSH_ORG"]
agent = os.environ["AGENT"]

res = requests.post(
    f"https://api.phoenix.so/o/{org}/agents/{agent}/connections",
    headers={"Authorization": f"Bearer {os.environ['RUSH_TOKEN']}"},
    json={
        "type": "mcp",
        "name": "notion",
    },
)

print(res.status_code, res.json())
```

## Responses

### 202

The sign-in, pending until the agent's user finishes it.

- `id` (string, required)
- `type` (string, required, one of `app`, `mcp`)
- `name` (string, optional): The name a session's `connections` and the template use.
- `agent` (string, required): The agent the connection belongs to.
- `url` (string, optional): The MCP server's address.
- `auth` (object, optional)
  - `mode` (string, optional, one of `oauth`, `bearer`, `none`)
- `status` (string, required, one of `pending`, `connected`, `failed`)
- `authorize_url` (string, optional): Where the agent's user signs in. Single use; expires in 10 minutes.
- `error` (object, optional)
  - `code` (string, optional, one of `connection_expired`, `cancelled_by_caller`, `connection_failed`)
  - `message` (string, optional)
- `tools` (array of object, optional)
  - `name` (string, optional)
  - `title` (string, optional)
  - `description` (string, optional)
  - `read_only` (boolean, optional)

### 400

The body is not `{type, name}` (`INVALID_BODY`, `UNKNOWN_FIELD`).

### 401

No bearer, an unknown, revoked or expired one, or an API key on a route keys cannot call.

### 404

No such agent made from a template of yours (`NOT_FOUND`).

### 422

The template does not name that connection, the MCP server takes a token rather than a sign-in, or the agent is not made from a template (`INVALID_BODY`); or the server cannot register Rush (`registration_unsupported`, `registration_failed`, …).

### 429

The account is over its request budget, 1,800 a minute shared by the person's API keys and console on every API host (`RATE_LIMITED`). The error names the limit. Wait `Retry-After` seconds.

## Example response (202)

```json
{
  "id": "e7d03b5a-9f1c-4a62-8b4e-0c6d2f9a1e37",
  "type": "mcp",
  "agent": "9b2f6c18-4e7a-4d35-8c91-5f0a3e7d2b66",
  "auth": {
    "mode": "oauth"
  },
  "status": "pending",
  "authorize_url": "https://mcp.notion.com/authorize?response_type=code&client_id=…&code_challenge=…&code_challenge_method=S256&state=…"
}
```
