Connect Botonom to Claude, ChatGPT and other assistants
Add Botonom to any MCP-compatible assistant and give it access to your agents, with permissions you approve and can withdraw at any time.
This guide begins with What this gives you, continues through Connecting, Permissions you approve, What the assistant sees, and finishes with Get notified when work finishes.
What this gives you
Botonom speaks the Model Context Protocol (MCP), the open standard assistants use to reach outside tools. Connect it once and your assistant can work with your agents directly, in plain language:
- "Ask my operations agent which orders are still waiting on stock."
- "Have the support agent draft a reply to the complaint that came in this morning."
- "What did the reporting agent find in yesterday's run?"
The agent answers with its own persona, its own rules and its own installed capabilities, inside the workspace you connected. Nothing about how it behaves changes; you are simply reaching it from somewhere else.
Use an MCP client that supports remote HTTP servers and Botonom’s OAuth flow. Tool availability depends on the client; automatic event notifications additionally require MCP Events support. The subscription-to-notification flow has been verified in ChatGPT Work.
POST /v1/agents/command. If you are building software rather than driving an assistant, the REST API is the better fit.Connecting
The server URL is the same everywhere:
https://mcp.botonom.com/mcp
Claude Code
claude mcp add --transport http botonom https://mcp.botonom.com/mcp
Claude desktop and web, ChatGPT, Copilot, Gemini, Windsurf
Open your assistant's connector or integration settings, choose to add a custom MCP server, and paste the URL above.
Cursor
Add it under Settings → MCP → Add new server, as an HTTP server with that URL.
Whichever client you use, the next step is identical: a Botonom page opens in your browser, you sign in if you are not already, you pick which workspace the application may reach, and you approve the permissions. Nothing is shared until you press Connect.
Permissions you approve
The consent screen lists four permissions separately, so you decide how far the connection reaches:
| Permission | What the application can do |
|---|---|
| See your agents | List the agents in the chosen workspace and read the results of past runs |
| Ask questions | Send an instruction and get the answer. The agent thinks, researches and writes, but changes nothing |
| Take action | The agent may use its capabilities to act: send an email, create a record, schedule work |
| Follow command updates | Receive events for selected agents or runs until monitoring stops or the subscription expires |
Take action and Follow command updates are never pre-selected, even when the application asks for it. Approve it only for applications you trust, because from that point the agent can do real work on your behalf rather than only talking about it.
Event subscriptions require both agents:read and agents:events. Sending a question also requires agents:ask; acting requires agents:act and an explicit action request.
A connection reaches exactly one workspace. If you work across several, connect each one separately.
What the assistant sees
Once connected, five tools become available. Your assistant picks between them on its own; you just describe what you want.
| Tool | Purpose |
|---|---|
list_agents | The agents in the connected workspace |
ask_agent | Give an agent an instruction and get its answer |
reply_to_run | Continue the same conversation: answer the agent's question or follow up |
get_run | Fetch the result of a longer job |
list_runs | Recent runs for an agent, with their results |
Only the tools your approved permissions cover are offered. If you did not grant Ask questions, ask_agent never appears.
Long jobs do not block the conversation: if an agent is still working after about a minute, you get a run reference back and the assistant can pick up the result later with get_run.
Talking to an agent through your assistant works like chatting with it in Botonom: the same skills, the same rules, and nothing lands in your Tasks list. Each question starts a conversation, and reply_to_run continues it, so the agent remembers what was said. When the agent needs something from you to continue (which report, which month), the run waits with the status waiting_input until your assistant passes your answer back.
Get notified when work finishes
With MCP Events, a supporting assistant can subscribe to a selected agent or run and respond when its state changes. You do not need to keep asking whether the work is finished.
| Event | Meaning |
|---|---|
agent.command.completed | A command completed |
agent.command.failed | A command failed |
agent.command.updated | Another command status change |
Subscriptions must include an agent_id, a run_id, or both. Events contain a run reference and status; the assistant reads the result with get_run. These are command events, not subscriptions to every message or business record in your workspace.
Try: “Let me know here when my reporting agent finishes. Read the result and stop monitoring after the first completed run.”
Stopping monitoring cancels the subscription; it does not cancel an agent’s running work.
Set up event notifications in ChatGPT
- In ChatGPT, open Plugins → Add → Create MCP App. Enter
https://mcp.botonom.com/mcpand choose OAuth. - Select your Botonom workspace. Approve See your agents and Follow command updates; add Ask questions if ChatGPT will start work. Grant Take action only when you need it.
- On the plugin’s page, confirm that the three events appear alongside its tools. For an existing connection, use Manage → Refresh tools after granting the new event permission.
- Start a new Work chat and ask it to monitor an agent’s completed commands. Confirm the subscription is established before starting a short test run.
- When an event arrives, ChatGPT can read its result and respond in that chat. Ask it to stop monitoring when you are finished.
We verified this sequence with a real command: subscribe, receive the completion event, read the result, post an automatic reply and unsubscribe. Client menus and feature availability can vary. If events appear but the chat cannot subscribe, refresh the plugin and try a new Work chat; a visible event list alone does not confirm an active subscription.
Event delivery and developer reference
MCP Events uses protocol version 2026-07-28. The authenticated MCP endpoint exposes server/discover, events/list, events/subscribe and events/unsubscribe; event subscriptions are separate from the four agent tools.
Botonom verifies the HTTPS callback before sending data and signs deliveries using Standard Webhooks. Subscription storage and queued deliveries survive restarts. Transient failures are retried with the same event ID; receivers should handle duplicates. Events are filtered before delivery and access is checked again during the subscription’s lifetime.
Subscriptions expire: the default is 24 hours, with a granted lifetime between five minutes and seven days. Clients must refresh before refreshBefore. Replay cursors can resume retained history; truncated signals that requested history is no longer available. Delivery is not a guarantee of immediate processing by the receiving assistant.
See the OpenAI MCP Events integration guide for the client protocol. Botonom’s REST webhooks and inbound skill events are separate integrations.
Reviewing and disconnecting
Every connected application is listed under Dashboard → Developers → Credentials → Connected apps, with the permissions it holds, when it was connected and when it was last used.
The connected-app card also lists event subscriptions, their status and last delivery. Use Stop to end one subscription without disconnecting the application.
Disconnect takes effect immediately. It withdraws the permission and invalidates every live session behind it, so the application stops working right away rather than at the next expiry.
If something does not work
The assistant says it cannot reach Botonom. Check the URL is exactly https://mcp.botonom.com/mcp. Some clients need the connection removed and re-added after a failed sign-in.
The agent answers but will not act. The connection does not hold the Take action permission. Disconnect it under Developers → Credentials and connect again, this time ticking that box.
"You are not a member of the selected workspace". You are signed in to Botonom with a different account than the one that belongs to that workspace. Sign out, sign back in with the right account and retry.
Sending instructions fails while reading works. Instructing an agent requires an owner or admin role in that workspace. Ask a workspace owner to raise your role, or to connect the application themselves.
Nothing happens after approving. Your assistant may have been waiting on a local callback that timed out. Start the connection again from the assistant.