# Connecting External Apps to Your Agents

Source: https://support.kapsulehost.com/en-nz/agents-connections

Connections let a Kapsule Agents expert work inside apps you already use, with your permission, and they are entirely separate from what an expert can do on your KapsuleHost account.

## What a Connection Is

A connection is a signed-in link between one of your experts and one external app. Once connected, that expert can use the app's tools in a conversation: reading a document, drafting a message, checking a record. Without a connection, the expert has no access at all.

Two things are worth being precise about:

- A connection grants access to **that app**, not to your KapsuleHost account. The two permission sets never mix.
- Anything that **changes** something in the connected app still goes through the same confirmation card as a change on your KapsuleHost account. Reading is immediate; writing asks first.

> **Note:** Connections live at **Agents**, then **Manage Connections**, or go straight to `/agents/connections`. The Agents home page also shows a Connections card with a few example apps.

## Which Experts Can Use Which Apps

The roster is deliberately conservative, and each expert only sees the apps its job needs. Some are limited to read-only tools even when the app itself can do more:

| Expert | External apps it can reach |
|---|---|
| Mara, Business Advisor | Stripe (read only) |
| Thea, Creative Writer | Notion |
| Sef, SEO Consultant | GitHub (read only) |
| Mila, Marketing Planner | Gmail, Slack, Notion, Google Calendar |
| Iris, Customer Comms | Gmail, Slack |
| Ash, Sales and Outreach | Gmail, Slack, Stripe (read only) |
| Pip, Policy and Docs | None |

Connecting an app does not hand it to the whole team. It becomes available only to the experts in the row above.

![The Connections catalogue in Kapsule Agents](https://support.kapsulehost.com/help/screenshots/agents-connections.26935fcd.webp)

## Connecting an App

1. Open **Agents**, then **Manage Connections**.
2. Browse the **Popular** tab, switch to **All Apps**, or type in the search box. Each card shows the app name and how many tools it exposes.
3. Click **Connect** on the app you want. The button changes to **Opening...** while the sign-in window is prepared.
4. Sign in to the app itself and approve the access it asks for.
5. You land back on the Connections page with a **[app] Connected** confirmation.

Once connected, the card shows a **Connected** pill, the account label you signed in as, and when the connection was last used, or **Not used yet**.

## Connection Statuses

| Status | What it means | What to do |
|---|---|---|
| Connected | Working. Your experts can use it. | Nothing |
| Pending | The sign-in was started but never finished. | Click **Finish Connecting** |
| Reconnect Needed | The access has expired or been withdrawn at the app's end. | Click **Reconnect** |

The **Reconnect Needed** state is normal over time: most apps expire the access they grant on a schedule. Reconnecting restores it without losing anything.

## How This Stays Safe

The Connections page states the safety model in three lines, and it is worth understanding rather than skimming:

- **Handled by a certified partner.** Signing in to an app is handled by our certified integration partner, which holds the grant. Your app password never touches KapsuleHost.
- **Confirmation before action.** Agents ask before acting. Anything that changes something needs your say-so first.
- **Instant revocation.** Disconnecting cuts access straight away, both here and with the app.

> **Warning:** Treat a connection like a key you have cut for someone. Connect the accounts you want your experts working in, not every account you own. If you are not sure whether an expert needs an app to do the job you have in mind, do not connect it: ask first, then connect.

## Disconnecting an App

1. Open **Agents**, then **Manage Connections**.
2. Click **Disconnect** on the connected app.
3. A confirmation appears: *Your team loses access to [app] right away. Anything it has already used stays in your past chats.*
4. Click **Disconnect** to confirm.

Access ends immediately. What that does **not** do is scrub the app's content out of conversations you already had: if an expert quoted a document into a chat last week, that text is still in the chat transcript. Disconnecting is about future access, not retroactive erasure.

## When Connections Is Not Available on Your Account

If the Connections page shows a single calm card reading **Connections Are Not Available Yet**, connecting external apps has not been switched on for your account. The card is explicit that nothing is connected and nothing has access, which is exactly the truth in that state. Your experts still work; they just cannot reach outside KapsuleHost.

The rest of Agents is unaffected. Chats, [Skills](https://support.kapsulehost.com/en-nz/agents-skills) and account reads all work as normal.

## What If It Fails

**"Permission was not granted, so nothing was connected."** You cancelled or declined at the app's own approval screen. Nothing was created. Click **Connect** again and approve the access.

**"Connections are unavailable right now. Try again in a moment."** The integration service could not be reached. This is deliberately fail-closed: rather than show a half-built list, the page shows nothing. Wait a minute and reload.

**"Connections could not be loaded."** Your settings are safe. Refresh the page. If it persists, [open a support ticket](https://support.kapsulehost.com/en-nz/opening-a-support-ticket).

**An expert says it cannot reach a connected app.** Check the table above. Not every expert is allowed every app, and an app connected for Iris is not automatically available to Mara.

**A connection sits on Pending.** The sign-in window was closed before it finished. Click **Finish Connecting** and complete it.

## What Connections Cost

Using a connected app in a conversation is metered like any other job. Each call an expert makes to an external app is charged at the connection-call weight, which is a fraction of what a long piece of writing costs. Reads on your KapsuleHost account remain free. The full weighting is in [How Agent Credits Work](https://support.kapsulehost.com/en-nz/agents-credits).

## Related

- [Kapsule Agents Overview](https://support.kapsulehost.com/en-nz/agents-overview)
- [Getting Started with Kapsule Agents](https://support.kapsulehost.com/en-nz/agents-getting-started)
- [Using Agent Skills](https://support.kapsulehost.com/en-nz/agents-skills)