Building block 2 · The basics
Connections
A connection links Charlie to an outside account, like Gmail or Slack. Charlie handles the sign-in and keeps the key safe. Your extension says which connection it wants and uses it.
What you'd use it for
- Switch on a service Charlie already knows how to sign in to, such as Atlassian.
- Call a web service that takes a pasted token, such as Slack.
- Bring in a hosted service that supplies its own tools, so you write none yourself.
In your manifest
The atlassian extension claims a sign-in Charlie already has. It declares no tools at all.
"connections": [ { "name": "atlassian", "authType": "oauth2-discovery", "transport": "mcp-server" } ]
The slack extension declares a new token connection of its own (trimmed).
"connections": [ { "name": "slack", "label": "Slack", "archetype": "token-static", "hosts": ["slack.com"], "fields": { "tokenLabel": "User token (xoxp-...)" }, "verify": { "url": "https://slack.com/api/auth.test", "method": "POST", "identityField": "user" } } ]
What each part means
| Field | What it does |
|---|---|
name | Which connection. For a built-in one, one of the names below. For a new one, your own name: lowercase letters, digits and hyphens. Required |
authType, transport | Used with a built-in name. Records how that service signs in and how Charlie talks to it. |
archetype | Used for a new connection. token-static for a pasted token, or mcp-discovery for a browser sign-in to a hosted MCP server. |
label | The name you see on the Connections page. Required with archetype. |
hosts | token-static only. The web addresses the token may be sent to. "*.example.com" covers subdomains. |
fields.tokenLabel | token-static only. The label on the box where you paste the token. |
verify | token-static, optional. An address Charlie checks a new token against before saving it, and which reply field names the account. |
url, scope | mcp-discovery only. The server's https address and the access to ask for. |
What you can and can't add today
Sign-ins Charlie already knows
Charlie has built-in sign-ins for selfactual, notion, atlassian, gmail and hub. Claiming one by name switches it on for your extension. A saved sign-in alone isn't enough. For a service like Atlassian, its tools only appear while a switched-on extension claims it.
Hosted MCP servers bring their own tools
Atlassian and Notion run their own MCP servers. Once you connect, Charlie offers that server's whole set of tools, so the extension needs no "tools" of its own. Charlie keeps those tools tucked away and finds them by search when a request needs one.
New connections you can declare
With token-static you can add any service that takes a pasted token. You paste it on the Connections page. Your handler calls the service with ctx.connections.slack.fetch(url), and Charlie adds the token itself. Your code never sees it.
With mcp-discovery you can point at another hosted MCP server that supports browser sign-in. No installed extension uses this yet.
What still needs a change to Charlie
Any other kind of sign-in, such as a REST service where you supply your own app's client ID. A built-in name Charlie doesn't know shows as Unsupported on the Connections page.
Things to know
- Restart Charlie after adding or changing a connection.
- You connect under Settings > Connections. An extension can also put a Connect button in its own settings panel, as Atlassian does.
- A token connection only calls https addresses on its
hostslist. - Two extensions can share a connection only if they declare it exactly the same way. Otherwise the second claim is skipped.
See it in
Every field, in full: reference: connections.