ChatGPT agents

Connect an agent you use in ChatGPT to the DonutChat conversations you choose. When you @mention it there, it reads the thread and replies under its own name.

What you need

A ChatGPT account that can add a custom MCP server. See OpenAI’s Add custom MCP server guide.
At least one DonutChat conversation in which you’re the owner or a manager.

Create the agent

Open External agents:

iPhone: go to Profile > Tools & content > My Bots, open Connections & secure requests at the bottom, and tap External-agent connections.
Android: go to Profile > Tools & content > My Bots, then ⋮ > External connections.
Desktop app: go to Settings > App > My bots, open Connections & permissions and click Manage connections.

Then add the agent:

Under Add agent, make sure OpenAI dots is selected.
Enter a Name of up to 64 bytes. The agent’s replies show this name.
Select the conversations the agent may use, up to 20.
Select Save preferences.

The list offers up to 100 conversations in which you’re the owner or a manager, most recently created first. It includes direct chats you started and My Memo, but not feed chats.
DonutChat creates a bot for the agent and adds it to the conversations you chose. You don’t create or add a bot yourself.
Instructions are saved in DonutChat only, and ChatGPT doesn’t receive them. Give the agent its instructions in ChatGPT.
You can have up to 3 external agents.

The agent’s bot appears in My Bots. The iPhone and Android apps show it as paused (Paused identity or Paused), and the desktop app labels it External agent. That’s expected: don’t switch the bot to Active, because the agent stops working if you do. Manage the agent in External agents, not from the bot’s home.

Connect it in ChatGPT

In ChatGPT, add a custom MCP server with the server URL https://api.donutchat.com/bots/agent-tools/mcp. OpenAI’s guide shows where to do this.
For authentication, choose OAuth. Leave any client ID and client secret fields empty.
When ChatGPT sends you to sign in, a DonutChat page opens in your browser and shows a 12-character code. Keep the page open. The page also says where to enter the code, but those directions don’t match the app, so follow the steps here instead.
In DonutChat, open External agents.
Select your agent in the list.
Open 2. Connected accounts and external authorization.
On iPhone, tap Refresh connected accounts. The code field stays unavailable until you do.
Check that Bot receiving access shows your agent. On Android, the button shows your agent’s name; if it says Choose a bot receiving access, tap it and pick your agent.
Enter the code in Code from authorization page.
Select Review client.
Read the request to use the selected bot’s permissions, then select Approve for selected bot.
Go back to the browser. The page continues to ChatGPT by itself within a few seconds.

You don’t enter your DonutChat password in the browser. You approve the connection in the app instead.
The section in step 6 also lists other account connections. You don’t need them for ChatGPT.
The code works once and expires after 10 minutes. If the page says This connection request has ended, start connecting again from ChatGPT.
If you use the ChatGPT desktop app, your browser may ask to open ChatGPT to finish. Allow it.
You can approve a code only for an OpenAI dots agent that has at least one allowed conversation and isn’t paused or disconnected.

Ask the agent

In ChatGPT, ask the agent once to watch for your mentions. For example:

Subscribe to Donut mention.created events and, when one arrives, read the thread and reply in it.

In one of the agent’s conversations, @mention the agent in a message, or in a reply in a thread you started. Pick it from the @ suggestions, or type its @username, which you can see on its bot in My Bots.
Wait for the agent to read the thread and reply in it.

Only your own messages reach the agent. When other people mention it, nothing happens, and mentions in a thread that someone else started don’t count.
DonutChat doesn’t show a working indicator for the agent. Its reply appears when ChatGPT posts it.
If the agent stops answering your mentions, ask it in ChatGPT to watch for them again.
You can also ask the agent directly in ChatGPT, for example to list your DonutChat conversations or to read a thread.

Check the connection

This step is optional. After ChatGPT has used the connection at least once, for example to list your DonutChat conversations, select your agent in External agents and select Check connector connection. Its status in the list changes to ready.

Change not confirmed… (desktop app: The change was not confirmed…) usually means ChatGPT hasn’t used the connection recently. Ask it to do something with DonutChat, then check again.
Later, the status can show authorization required again when ChatGPT hasn’t used the connection for a while. That doesn’t necessarily mean the agent is disconnected.

What the agent can see and do

The agent works only in the conversations you allowed, and only with your messages and the threads you started there:

It can list the conversations you allowed.
It can read your own recent text messages in them, 20 at a time, each shortened to 1,000 characters.
It can read a thread you started: the first message (up to 8,000 characters) and the 20 most recent text replies (up to 2,000 characters each), including other members’ replies and its own.
It can reply in a thread you started, under the agent’s name. Everyone in the conversation can see the reply.

It can’t see conversations you didn’t allow, read other people’s messages outside your threads, open attachments, post new messages in the chat, or reply in threads that someone else started. If you stop being the owner or a manager of a conversation, or the agent’s bot is removed from it, the agent can’t use that conversation anymore.

Limits

Item	Limit
External agents	3 per account
Name	1–64 bytes
Instructions	16,000 characters, kept in DonutChat
Conversations	20 per agent
Approval code	12 characters, expires after 10 minutes, works once
Reply	8,000 bytes (UTF-8)

In byte limits, each English letter, digit or space counts as 1 byte. Accented letters, other scripts and emoji take 2 or more bytes each, so a name that uses them fits fewer characters.

Pause, reconnect, disconnect or delete

Select the agent in External agents to see these controls:

Control	What it does
Pause	Cuts off the agent’s access right away.
Allow reconnection	Shown while the agent is paused. Lets you connect it again from ChatGPT with a new code.
Disconnect	Ends the agent’s connection for good. Afterward you can only delete it.
Delete configuration	Removes the agent’s settings and the bot DonutChat created for it. This can’t be undone.

Selecting Save preferences for an existing agent, for example to change its conversations, also ends its access. Connect it again from ChatGPT.
To disconnect ChatGPT but keep the agent’s settings, select Revoke external-agent access for selected bot in 2. Connected accounts and external authorization. Connect again from ChatGPT when you want to use the agent.
After you connect again, ask the agent in ChatGPT to watch for your mentions again, and repeat any mention you sent while it was disconnected.