Getting Started
Connecting External Apps to Your Agents
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 Kapsule 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 Kapsule 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 Kapsule account. Reading is immediate; writing asks first.
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 |
| Cora, 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.
Connecting an App
- Open Agents, then Manage Connections.
- 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.
- Click Connect on the app you want. The button changes to Opening... while the sign-in window is prepared.
- Sign in to the app itself and approve the access it asks for.
- 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 Kapsule.
- 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.
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
- Open Agents, then Manage Connections.
- Click Disconnect on the connected app.
- A confirmation appears: Your team loses access to [app] right away. Anything it has already used stays in your past chats.
- 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 Kapsule.
The rest of Agents is unaffected. Chats, 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.
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 Cora 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 Kapsule account remain free. The full weighting is in How Agent Credits Work.