Guides
Circles guides
How to set Circles up, step by step: link your WhatsApp, choose which chats your agents see, and connect your agent. The technical reference, written for the agents themselves, is on its own page.
Circles connects the WhatsApp chats you choose to the AI agent you choose. You link your own number as a linked device, open the chats an agent may read (and, if you want, send in), and connect the agent by address or with a token. Every connection can be cut with one press. As of October 2026.
Updated
Quickstart
From nothing to an agent reading your chats in a few minutes.
Start a trial
At usecircles.app, press Start now, no commitment and enter your WhatsApp number. A sign-in link arrives on WhatsApp; it works once, for ten minutes. Add a card at checkout; you're not charged today. Pricing.
Link your WhatsApp
In Circles, link your number as a linked device: a code you type on your phone, or a QR you scan from a computer. Details.
Check your chats
On a new number, groups and direct chats open for reading by default. Hide what an agent should never see, and open a chat for sending only where you want replies. Details.
Connect your agent
Instinct: one tap, then send. Claude, ChatGPT, Codex: paste
https://app.usecircles.app/api/mcpand approve. Claude Code, Cursor, Grok: a token and one config block (Claude Code: one command). Details.Ask
"What did I miss in the parents group?" The agent calls
activity, thencatch_up, and answers with voice notes already as text.
For a client that takes a config file, this is the whole setup:
# Claude Code, one command (the token comes from Circles: New token > Copy config)
claude mcp add --transport http circles https://app.usecircles.app/api/mcp \
--header "Authorization: Bearer circ_..."
# Or the same as a JSON block (Claude Code's .mcp.json needs "type": "http";
# Cursor, Grok and other MCP clients take the same block)
{
"mcpServers": {
"circles": {
"type": "http",
"url": "https://app.usecircles.app/api/mcp",
"headers": { "Authorization": "Bearer circ_..." }
}
}
}Link your WhatsApp
Circles links your existing personal number as a linked device, the same mechanism as WhatsApp Web. Your phone keeps working as always, and the people you talk to see no change. You need no WhatsApp Business account and no second number.
- Sign in at app.usecircles.app with your WhatsApp number. Circles sends a sign-in link from its own WhatsApp number. There is no password.
- Choose how to link. On your phone: Circles shows a code; in WhatsApp go to Settings, Linked devices, Link a device, choose to link with a phone number, and type the code. On a computer: scan the QR from WhatsApp's Linked devices screen.
- Your phone may show a notice that a device was linked. That is Circles.
- History arrives in about 5 to 15 minutes. New messages arrive as they are sent.
A number links only once it is verified as yours: you signed in with it, or you tapped a link sent to it. Each customer connects through a dedicated IP address shared with no other customer; if none is ready, linking waits until one is. It never uses a shared address.
History. Full history by default: everything WhatsApp delivers to a linked device (often years) plus everything new, kept while the number is linked. WhatsApp decides how much of your phone's history it sends. You can narrow it to the last 90, 60 or 30 days; a shorter window deletes what falls outside it, and widening it later applies forward only.
Files. Photos, documents, video and audio within about 25 days of the message are downloaded in the background. Older ones are on_request: an agent asking for one makes your phone re-upload it, so the phone needs to be online.
Unlinking removes the device from WhatsApp and, once WhatsApp confirms, deletes everything stored from the number. Your settings and per-chat choices stay for when you link again.
Choose what agents see
Permissions belong to chats: every agent you connect sees the same open chats, within what its own sign-in allows.
| Setting | What it does | Default |
|---|---|---|
| Hidden | The chat does not exist for agents: not listed, not searchable, never named, even in a refusal or the log | The number default for numbers first linked before 2026-09-29 |
| Read | Agents read and search it and open its files. There is no way to send. | Groups and direct chats on a new number |
| Read and send | Agents may also send there, as you, within the daily cap. Circles warns first that messages will look as though you sent them. | Never by default |
| Never store | Nothing from the chat is written at all, and it cannot be opened | Off |
| Include direct chats | Off: no agent sees any one-to-one chat, whatever its level | On for numbers first linked from 2026-10-27 |
| Number default | The level a chat gets when it first appears. Your hand-set choices are never changed by it. | Read |
| Daily send cap | Messages per day for the whole number, across all agents, counted per UTC day | 5 (choose 5, 10, 20 or no cap) |
| History window | How far back Circles keeps messages | Full history (or 90, 60, 30 days) |
A new group stays hidden until WhatsApp delivers its name. A chat you open today returns its history from before you opened it. An archived chat stays readable and is marked archived: true. Starting a chat with someone new (by number or saved contact) is possible only when the number's default is read and send.
Connect an agent
Each agent connects the way it connects best. Every connection is listed on the Agents page in Circles, where one press disconnects it.
| Agent | How it connects | What you do |
|---|---|---|
 Instinct | One-time code sent from WhatsApp | Tap Connect Instinct; WhatsApp opens with the message written; press send. No key, ever. |
 Claude | By address, OAuth | Add a custom connector with https://app.usecircles.app/api/mcp, connect, approve on Circles' page |
 ChatGPT, Codex | By address, OAuth | Add an MCP server or custom connector with the address and approve. The app shows its current steps. |
 Claude Code | Token in the MCP config | New token, then run the claude mcp add --transport http command above (preferred), or paste Copy config into .mcp.json with "type": "http" |
 Cursor | Token in the MCP config | New token, Copy config, paste into Cursor's MCP settings. Cursor cannot connect by address. |
 Grok | Token in the MCP config | New token, then add Circles as a remote MCP server with it |
| Your own agent | HTTP API with a key, or MCP with a token | New token, choose API, hand the agent the instructions and then the key, as two messages |
No "Add to Claude" or "Add to Cursor" buttons exist. Connecting by address is the one-step path for Claude, ChatGPT and Codex. A token is the path for clients that take a config file.
A token is for one agent, and the activity log shows the name you give it. When handing a key to a chat-based agent, Circles gives you two messages: the instructions first, then the key alone, so the key ends up only in the agent's secrets.
For agents: the API and MCP documentation
The technical reference lives on its own page, in English, written for the agents themselves: the nine MCP tools and their parameters, what answers and refusals look like, OAuth and tokens, the HTTP API, every limit and the changelog. An agent that is connected, or about to be, can read it to learn what Circles offers and how to use it well.
Circles API and MCP documentation (also as Markdown).
Questions and answers
What is the Circles MCP server URL?
https://app.usecircles.app/api/mcp. Paste it into Claude, ChatGPT or Codex and approve on Circles' page, or use it with a token in a client that takes a config file.
Where is the technical reference?
On the API and MCP documentation page, in English, written for agents: tools, answers, auth, the HTTP API and limits.
Connect your WhatsApp to your agent today.
14 days free. Link your number, pick the chats, then connect Instinct with one tap or Claude, ChatGPT and Codex with one address.