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

# Connections

> plungeai_connections manages the accounts your agents act through, action for action the One API's /v1/connections. Credentials are stored encrypted on the compliance database and never come back out: a list shows provider, method, status and when, nothing else. Full parameter table: 14.22.


Source: `orchestration/mcp-gateway/tools-connections.ts` (`ConnectionsSchema`, `plungeaiConnections`), `orchestration/mcp-gateway/ops/connections.ts` (the store, the subject rule, the connect link), `core/core-secrets/UserCredentialsService.ts`, `core/core-secrets/connect-token.ts`, `orchestration/api-gateway/routes/connections.ts` (the REST twin).

`plungeai_connections` manages the accounts your agents act through, action for action the One API's `/v1/connections`. Credentials are stored encrypted on the compliance database and never come back out: a list shows provider, method, status and when, nothing else. Full parameter table: [14.22](/mcp/tool-reference#1422-plungeai_connections).

## 17.1 Whose account: `on_behalf_of`

Without `on_behalf_of` a call acts on your own account. With it, it acts on one of **your customers**: the id is yours to choose (1–128 characters of `A-Z a-z 0-9 _ . -`, no `..`), and the row is kept under your account, so no other key can reach it. An empty or malformed value is refused (`invalid_on_behalf_of`), never read as "me".

## 17.2 Actions

| `action` | Needs | REST twin | Answer (`structuredContent`) |
|---|---|---|---|
| `list` | optional `on_behalf_of` | `GET /v1/connections` | `{connections: [{provider, on_behalf_of, method, status, connected_at}]}`. Every list is written to the secrets audit log |
| `add` | `provider`, `api_key`; optional `api_secret`, `on_behalf_of` | `POST /v1/connections/{provider}` | `{provider, on_behalf_of, status: "connected"}`. Where the platform has a probe for the provider, the key is checked first; a key the provider rejects is `credential_rejected` |
| `remove` | `provider`; optional `on_behalf_of` | `DELETE /v1/connections/{provider}` | `{provider, on_behalf_of, status: "disconnected"}`; nothing to remove is `connection_not_found` |
| `link` | `provider`; optional `return_url` (https), `on_behalf_of` | `POST /v1/connections/{provider}/link` | `{url, expires_at}`: a signed Studio link, single use, valid 15 minutes. Send it to whoever owns the account; they connect there (OAuth or key) and return to `return_url` |

`provider` must be a provider the platform can connect: a key-based one (`stripe`, `openai`, `apollo`, `custom`, …), an OAuth one (`github`, `google-gmail`, …) or one an agent's connection prompt names. Anything else is `not_found` `unknown_provider`. The key and secret are redacted from the activity log like every other secret-named argument.

## 17.3 Refusals

The same shape as [16.4](/mcp/companies#164-answers-and-refusals): `isError: true` text `<word>: <message> (<code>)` and `structuredContent.error = {status, code, message}`.

| `status` word | Codes |
|---|---|
| `invalid` | `invalid_params` (no `provider`), `missing_api_key`, `credential_rejected`, `invalid_on_behalf_of`, `invalid_return_url` |
| `forbidden` | `owner_not_found` (`link` from a key whose user account is gone) |
| `not_found` | `unknown_provider`, `connection_not_found` |
| `unavailable` | `connections_unavailable` (the credential store is not reachable from this deployment) |

Try asking:

- *"What accounts have I connected?"* → `list`
- *"Send my customer acme-42 a link to connect their GitHub."* → `link` with `on_behalf_of: "acme-42"`
- *"Disconnect Stripe."* → `remove`

List your connections (read-only):

```bash
curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_connections","arguments":{"user_request":"what accounts have I connected?","action":"list"}}}'
```

Make a connect link for a customer. This signs a link (not verified here):

```bash
curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_connections","arguments":{"user_request":"send acme-42 a link to connect GitHub","action":"link","provider":"github","on_behalf_of":"acme-42","return_url":"https://app.example.com/connected"}}}'
```