A connection is one external account that one Agent may use: a Zendesk login, a Gmail inbox, an MCP server. Where a channel grant decides where an Agent may work, a connection decides what it may reach. This page covers connecting from Admin, connecting from Slack, custom MCP servers and REST APIs, what ready means, and disconnecting.
Every connection belongs to one Agent for its lifetime. Authorizing the same external account for a second Agent creates a separate connection with its own consent.
Prerequisites
- Slack is connected. Admin refuses Agent connections before that, with “Connect Slack before adding Agent connections.”
- The Agent is saved. A new Agent shows “Save this Agent first, then add Team connections or your personal accounts.”
- You may edit the Agent. Owners and Admins may edit any Agent. A Member may edit an Agent they created, or any Agent whose edit policy is set to all workspace members.
- Team accounts need the Admin or Owner role. Any Member may create a personal account for an Agent they can edit.
Connect from Admin
Open the Agent's Connections tab
Go to Agents → the Agent → Connections. Accounts already attached are listed under In this Agent; the catalog below it is headed Connect a new account.
Find the service
The catalog offers 35 connector presets. Type into Search connectors to filter by name or description, then choose Connect on the row. Presets this Agent already owns are hidden from the catalog.
Choose who uses it
Who uses this connection? has two answers and no default. Personal means each person signs in with their own account, and the Agent uses yours only for your requests. Team means one shared account for everyone who can use that Agent. You cannot continue until one is chosen.
Label the account
Give the account a label, such as Work Zendesk, and a purpose, such as Support tickets for the Acme team. People can then say “use my work account” in Slack to pick this connection.
Sign in, or paste the credential
OAuth presets show Continue to sign in and hand you to the provider. Token presets show one write-only Credential field, stored once outside the Agent record and never returned to the browser. Choose Connect and add.
A few presets ask for one more detail first: Zendesk asks for your workspace subdomain, Supabase asks for a project reference and whether the Agent gets read-only or read and write access, and Sentry can narrow the connection to one organization or one organization and project.
What each auth kind asks for:
| Auth kind | What Admin asks for | Presets |
|---|---|---|
| OAuth | Nothing to paste. You sign in with the provider and approve the access. | Linear, Atlassian, Sentry, Cloudflare API, Supabase, PostHog, Airtable, Intercom, Granola |
| Bearer token | One token in a write-only field, sent as an Authorization bearer. |
Stripe, Neon, Monday.com, Firecrawl, Hugging Face, Ahrefs, Fireflies, incident.io, LunarCrush |
| Custom header | One key, sent in the header the provider names. | Gamma (X-API-KEY), Exa (x-api-key, optional) |
| REST API token | One token in the Authorization header, with the provider’s prefix. |
Asana (Bearer), Zendesk (Basic) |
| Managed | Hosted sign-in through the managed connector provider. | Gmail, Google Calendar, Google Drive, Google Sheets, Google Docs, Google Slides, Notion, HubSpot, Gong, Google Ads, YouTube, Google Analytics, Google Search Console |
Stripe wants a restricted key (rk_), not a full secret key. Exa also works without a key at the provider’s anonymous limits.
For a token-based MCP preset, Chickpea connects to the server before saving anything and records the tools it discovered. A server that does not answer fails with “Could not connect to this MCP server.” and no connection is added.
Connect from Slack
Ask the Agent. Credentials are never requested in Slack or in model context.
@supportconnect Zendesk
The Agent replies with a Chickpea link instead of a form. Opening it shows a page headed Connect Zendesk to support, which asks the same two questions: who uses this account (My connection or Team connection), and the credential or the provider sign-in. The link is good for one frozen action against one Agent, expires 24 hours after it was issued, and cannot be redirected to another requester, Agent, or action by whoever holds it.
When the page finishes it says the connector is now connected to the Agent, and that your team or personal connection is ready. Chickpea posts the completion receipt back to the Slack thread the request came from. The same link mechanism is what the management MCP returns to a coding agent.
Connect a custom MCP server or API
Choose Custom connection → Connect at the bottom of the catalog, then pick a Connection type.
MCP server. Give the Server URL and, if the server needs one, a credential, which is sent as a bearer token. Leave the credential empty for a server that needs none. URLs must use https; Chickpea rejects localhost, hostnames ending in .local, .internal, or .localhost, private and internal IP addresses, bare hostnames without a dot, and URLs with an embedded username or password. Fill Allowed tools with comma-separated names; that list becomes the Agent binding’s maximum authority.
REST API. Give the API base URL. Its host becomes the connection’s only allowed host and its path becomes the path prefix, so https://api.example.com/v1 allows exactly that host and everything under /v1. The credential is sent as Authorization: Bearer <token>, and GET, HEAD, POST, PUT, PATCH, and DELETE are allowed. Fill Capabilities with comma-separated names.
Two enabled connections on the same Agent may not cover the same URL space. Saving an overlap is refused with “enabled connections must not cover overlapping URLs; narrow their hosts or path prefixes so each connection governs a distinct URL space”.
Verify
A connection is usable on a turn only when all of this holds: the binding is enabled, the account is ready, and, for a personal account, the person asking is the account’s owner.
Ready means the credential is stored, the sign-in finished, or the MCP server needs no credential at all. In In this Agent, a ready row carries no status label. Other rows carry one, with the button that clears it:
| Status | What it means | Button |
|---|---|---|
| Setup required | Setup never finished, or a managed account still needs a resource chosen | Choose |
| Needs attention | The credential or authorization is missing or no longer works | Sign in or Reconnect |
| Disconnected | The connection was revoked | none |
Then prove it in Slack, in a channel the Agent is published to:
@supportlook up ticket 4821 in Zendesk and tell me its status
A real answer from the account is the proof. Reading is enough: minor reversible writes may proceed without confirmation, and consequential ones (sending a message or email, deleting, publishing, broad or bulk changes) require confirmation unless the saved Agent instructions explicitly authorize that class of action.
Disconnect an account
Open the row’s ⋯ menu in In this Agent and choose Disconnect account…. Chickpea asks to confirm: “This Agent will lose access and dependent schedules will pause.” For a managed account it also warns that the provider may still list the authorization until you remove it in that provider’s own account settings.
Disconnecting a team account needs the same role that creating one needs. Dependent schedules are paused before the credential is removed, so a schedule never runs on an account that is half gone.
On Node
Connecting works the same way on Node, with one difference behind it. Node runs no scheduler, so there are no schedules to pause or retire when a connection is disconnected. A Node deployment can also reach your own network directly, which is why the MCP URL guard rejects local and private targets when you save a connection and again on every turn that uses it.
Next steps
- Agents: the rest of what an Agent is made of, including connections in depth and managed connectors.
- How Chickpea works: why the model picks a connection by ID and never sees the secret.
- Authority and confirmation: the authority model behind grants, connections, and confirmation.
- Sign-in, members, and roles: roles, sign-in, and who may change what.