ChatBooster MCP guide
ChatBooster provides an MCP (Model Context Protocol) server. Connect it to an AI tool that supports MCP, such as Claude or Cursor, and you can look up customers, triage your inbox, reply to existing conversations, and review broadcast and analytics results in plain language.
If you only want to use ChatBooster in Claude on the web, see Use ChatBooster in Claude. This page covers every way to connect, and what an AI tool can do once it is connected.
Server details
| Item | Value |
|---|---|
| Server URL | https://mcp.chatbooster.ai/mcp |
| Transport | Streamable HTTP (a remote server; nothing to install on your machine) |
| Authentication | OAuth authorization, or an MCP token |
Before you start
- A ChatBooster account.
- A workspace with at least one channel connected (WhatsApp, Messenger, Instagram, LINE and so on). Without a channel there is no customer data to query yet.
- An AI tool that supports remote MCP servers.
Choose how to connect
| Method | When to use it | Permissions |
|---|---|---|
| OAuth authorization | Your AI tool supports OAuth sign-in, for example Claude connectors or Claude Code | You choose read-only, or read plus actions, when you authorize |
| MCP token | Your AI tool needs you to enter a credential yourself, for example Cursor's config file | The same as your role in ChatBooster |
Either way, the AI tool can only see and do what your ChatBooster role already allows on the web.
Option 1: OAuth authorization
- In your AI tool, add a remote MCP server with the URL
https://mcp.chatbooster.ai/mcp. - The AI tool opens the ChatBooster sign-in page. Sign in or create an account. We'll email you a verification code.
- Choose the workspace to authorize, review the requested permissions, and click Authorize.
- You are taken back to the AI tool and the connection is ready.
The authorization page lists the permissions the application is asking for:
| Scope | What it allows |
|---|---|
chatbooster:read | Read contacts, conversations, messages, tags, lists, broadcasts and analytics |
chatbooster:write | Add or remove contact tags, add notes, change conversation status, assign conversations, set conversation labels, and send messages in existing conversations |
offline_access | Stay connected without signing in again |
Check who you are authorizing
The authorization page shows the domain your data will be sent to. Make sure you started this connection yourself in the AI tool before you click Authorize.
Claude (web): open Settings → Connectors, find ChatBooster and click Connect. See Use ChatBooster in Claude for the full steps.
Claude Code: run the command below in your terminal, then type /mcp in Claude Code to sign in.
claude mcp add --transport http chatbooster https://mcp.chatbooster.ai/mcpOption 2: MCP token
An MCP token is a personal access credential, for AI tools that cannot go through the OAuth sign-in flow.
Create a token
- Log in to ChatBooster and go to Account settings → MCP connection.
- Click Create token and give it a name. Name it after the tool or device you are connecting (for example "Cursor — work laptop") so you know which one to revoke later.
- Copy the token right away. It is shown only once. If you lose it, revoke it and create a new one.
Keep your token safe
- The token carries your own permissions. Do not hand it to a teammate. Each member should create their own.
- An AI tool that holds the token can perform actions, including sending messages to customers.
- Do not commit the token to a code repository or paste it anywhere public. If you think it has leaked, revoke it immediately under Account settings → MCP connection.
Add the token to your AI tool
Send the token in a request header:
Authorization: Bearer YOUR_MCP_TOKENCursor: add this to ~/.cursor/mcp.json (or .cursor/mcp.json inside a project):
{
"mcpServers": {
"chatbooster": {
"url": "https://mcp.chatbooster.ai/mcp",
"headers": {
"Authorization": "Bearer YOUR_MCP_TOKEN"
}
}
}
}Claude Code:
claude mcp add --transport http chatbooster https://mcp.chatbooster.ai/mcp --header "Authorization: Bearer YOUR_MCP_TOKEN"Other AI tools: any tool that supports remote MCP servers (Streamable HTTP) and custom request headers will work. Enter the server URL and the Authorization header above.
Your first task
Once connected, ask your AI tool:
Check my ChatBooster workspace setup.
It tells you whether your workspace is ready. If no channel is connected yet, open the setup page it gives you, connect a channel, and send a test message from your own number or page. Once the workspace has data, try:
- Show my five most recent open conversations and summarize them.
- List my five most recent contacts and their tags.
- Did any customer ask about a refund last week?
- How did my last broadcast perform?
Available tools
Your AI tool picks from the tools below based on what you ask. You do not need to remember the names.
Reading data
| Tool | What it does |
|---|---|
search_contacts | Search contacts by keyword, tag, list or channel |
get_contact | View one contact's full details |
list_contact_notes | View a contact's notes |
get_contact_activity | View a contact's activity log, such as being added to a list, tagged, or edited |
list_conversations | List conversations, filtered by status, assignee or channel |
get_conversation_messages | Read the full messages of one conversation |
search_messages | Search messages by keyword across conversations |
list_conversation_labels | List conversation labels and how many conversations each has |
list_tags | List contact tags |
list_contact_lists | List contact lists |
list_custom_fields | List custom fields |
list_channels | List connected channels |
list_broadcasts | List broadcasts and their results (reach, delivered, read, replied, failed) |
get_broadcast_stats | View the latest progress and results of one broadcast |
get_analytics | Get summary numbers for a time range, such as new contacts or messages sent |
Taking actions
These tools change data in your workspace. With OAuth authorization, they need the chatbooster:write scope.
| Tool | What it does | Can it be undone? |
|---|---|---|
add_contact_tag | Add a tag to a contact | Yes, remove the tag |
remove_contact_tag | Remove a tag from a contact | Yes, add it back |
create_contact_note | Add a note to a contact | Delete it in ChatBooster on the web |
update_conversation_status | Set a conversation to open or closed | Yes, change it back |
assign_conversation | Assign a conversation to a member, or unassign it | Yes, reassign it |
set_conversation_label | Set a conversation's label. A conversation has one label, so this replaces the current one | Yes, set it again |
clear_conversation_label | Clear a conversation's label | Yes, set it again |
send_message | Reply to a customer with text in an existing conversation | No |
Workspaces
| Tool | What it does |
|---|---|
list_workspaces | List the workspaces you can access |
switch_workspace | Switch the workspace you are working in |
get_workspace_setup_status | Check whether the workspace has a channel and data yet, and what to do next |
Sending messages
send_message delivers a real message to your customer and cannot be recalled. Check the recipient and the content before you let your AI tool send it.
- It can only reply in an existing conversation. It cannot start a new conversation with an arbitrary number.
- Text only for now.
- Broadcasts can be viewed and analyzed, but not created or sent through MCP.
Multiple workspaces
An AI tool works in one "current workspace" at a time. Ask it to list your workspaces, then switch to one.
Switching is persistent
Once you switch workspace, the choice is saved and applies to every AI tool that uses the same connection or token, not just the current chat. Take care when one token is shared between several tools.
Language
The tool descriptions and messages your AI tool sees can be in Traditional Chinese or English. Change this under Account settings → MCP connection. Reconnect your AI tool for the change to take effect.
Plan and billing
Your workspace's ChatBooster plan applies in your AI tool as well. Manage your plan and billing on the ChatBooster website. You don't need to reconnect after changing plans.
Troubleshooting
| What you see | What to do |
|---|---|
The AI tool says authorization is required, or returns 401 | The connection has expired or the token was revoked. Reconnect, or create a new token. With a token, check that the header is Authorization: Bearer <token> |
| The AI tool asks you to choose a workspace | Ask it to list your workspaces, then switch to one |
| "Permission denied" | Your role in this workspace doesn't allow that action. Contact your workspace owner |
| Actions don't work | With OAuth authorization, you may have granted read-only access. Disconnect, then authorize again and allow actions |
| Empty results | Ask the AI tool to check your workspace setup. You may not have a channel connected, or the channel has no messages yet |
| Sending a message reports a WhatsApp payment problem | Add a payment method in Meta first, then simply retry. You don't need to reconnect ChatBooster |
| "Too many attempts" at sign-in | Wait 15 minutes, then request a new code |
Disconnect
- OAuth authorization: remove the ChatBooster connection in your AI tool, or go to Account settings → MCP connection in ChatBooster and revoke it under "Authorized applications".
- MCP token: go to Account settings → MCP connection and click Revoke. Any AI tool using that token stops working immediately, and this cannot be undone.
Disconnecting doesn't delete any ChatBooster data.
Privacy
See our Privacy Policy for what we process and how to request deletion. Questions: [email protected].