Skip to content

Corebee MCP Server

The Corebee MCP server lets any Model Context Protocol client, such as Claude, Meta Muse, another MCP-capable agent or your own tooling, operate AI customer support for a connected organization. Read and reply to conversations, manage contacts, search and edit the knowledge base, and pull metrics, all scoped to a single organization and gated by OAuth 2.1.

Endpoint

The server speaks Streamable HTTP at a single canonical endpoint. Point your MCP client at:

https://corebee.ai/api/v1/mcp/stream

Discovery metadata lives at /.well-known/mcp/server-card.json and /.well-known/oauth-protected-resource. The legacy SSE route at /api/v1/mcp is deprecated. Use the endpoint above.

Requirements

  • A Corebee account on any plan, including Free (1 seat, web chat only, 50 AI-answered conversations a month). MCP access is not tied to a plan. Pro and Business start with a 14-day free trial and add email, SMS, WhatsApp, Instagram, Messenger and phone.
  • Replies reach customers only on channels your workspace has connected.
  • Corebee is for businesses; users must be 18 or older.
  • Data is hosted in Mumbai, India; there are no regional restrictions on use.
  • Any member of a workspace can connect, except members limited to specific sub-accounts. You sign in with your Corebee login. Apps such as Meta Muse then ask you to approve access on a Corebee consent screen. Corebee's own Claude connector is approved when you sign in.
  • Access follows your role in the workspace. Owners can grant every scope. Agents can read and change conversations, contacts and the knowledge base, but cannot delete data or change settings. Viewers are read-only.
  • One connection covers one workspace: the one Corebee opens when you sign in.

Authentication (OAuth 2.1)

Every request is authenticated with an OAuth 2.1 bearer token passed in the Authorization header. Compliant MCP clients complete the flow automatically:

  1. Protected-resource discovery. On a 401 the client reads /.well-known/oauth-protected-resource (RFC 9728) to find the authorization server.
  2. Dynamic Client Registration (DCR). The client registers itself at /api/v1/mcp/oauth/register (RFC 7591), so no manual client ID is needed. Meta Muse, if it asks for a client ID, uses the public client ID muse (see Use Corebee in Muse). That ID works only with Muse's own callback addresses.
  3. Authorization Code + PKCE (S256). The user approves access in the browser; the code is exchanged with a code_verifier / SHA-256 code_challenge. Plain challenges are rejected.
  4. Token issuance. The token endpoint returns an RS256-signed access token scoped to one organization and the scopes the user granted. Access tokens last 1 hour. Refresh tokens last 30 days and are rotated on every use. A repeat of the same refresh within 15 seconds returns the same new pair. After that an old refresh token is refused. If it is used after the connection has already refreshed again, it is treated as stolen: the whole connection is revoked and the user must approve again.

The RFC 8707 resource parameter is optional. If you send it, it must be https://corebee.ai/api/v1/mcp/stream.

Authorization: Bearer <access_token>

Use Corebee in Muse

Meta Muse can run your Corebee support desk for you. Ask in plain words and it reads your inbox, answers from your own knowledge base and takes action: it assigns conversations, sets priority, leaves notes for your team and replies to customers when you tell it to. Connect it in one of two ways:

  • From the Muse directory. Once Corebee is listed, pick Corebee and follow the sign-in steps.
  • As a custom connector. Add a connector with the MCP URL below and choose OAuth.
MCP URL
https://corebee.ai/api/v1/mcp/stream
Client ID
Muse connects with the public client muse (PKCE, no secret), so leave the secret empty. A confidential client, muse-meta, is also available once its secret is configured; until then it is disabled. Both work only with Muse's callback addresses below.
Callback
https://agent.meta.ai/api/hatch/oauth/callback
https://muse.ai/api/hatch/oauth/callback
Sign-in
OAuth 2.1 with PKCE (S256). Dynamic client registration also works.
  1. Start the connection in Muse.
  2. Sign in to Corebee when Muse sends you there.
  3. Check the Corebee consent screen. It shows the address the app returns to (agent.meta.ai or muse.ai for Muse) and the permissions it asks for. Choose Read only or Read and make changes. Muse is never offered delete permissions. Click Allow access. Corebee shows this screen every time Muse connects.
  4. Test the connection with a real request, not only the “connected” badge. Try one of the prompts below.

“Catch me up on my support inbox. Group the open conversations by topic, rank them by urgency, and tell me who has waited longest.”

Expected: Reads every open conversation with list_conversations and get_conversation, then groups, ranks and times them in one answer. No writes.

“Find the most urgent open conversation, mark it urgent, assign it to a teammate, and leave them an internal note with what the customer needs.”

Expected: Reads your open conversations, looks up your team with list_team_members, then calls set_priority, assign_conversation and add_conversation_note. The note is internal: the customer never sees it.

“How did support go over the last 30 days? Tell me how many replies the AI sent, how fast we answered, how happy customers were, and our busiest days.”

Expected: Calls get_metrics and get_trends and turns the numbers into a short report. No writes.

“Find the customer asking about a return, draft a reply from my knowledge base, and send it after I approve.”

Expected: Finds the conversation, checks your articles with search_knowledge or a2a_knowledge_agent, and shows a draft. It calls reply_to_conversation, which sends the reply to the customer, only after you approve.

“List my open Corebee conversations and tell me what each customer wants.”

Expected: Quick check that your data comes through: calls list_conversations (open by default), then get_conversation on each one, and sums up each request. No writes.

Muse can use only the Muse tool set. It gets only what you approve and what your role allows. Revoke it any time under Connected apps.

Use Corebee from Cursor, Claude Code and Grok Build

The Corebee plugin points your coding agent at this server and adds six skills that tell it how to use Corebee safely: inbox triage, reply drafting, customer lookup, knowledge base, support report and widget setup. It ships one rule and one MCP server entry, with no hooks and no scripts, so installing it runs nothing on your machine. It is open source under the MIT licence at github.com/Corebee-AI/corebee-plugin.

  • Cursor. Install it from the community directory listing at cursor.directory/plugins/corebee, then sign in when Cursor opens the Corebee consent page. More on the Cursor integration page.
  • Claude Code. Run /plugin marketplace add Corebee-AI/corebee-plugin and /plugin install corebee@corebee, then run /mcp, pick corebee and choose Authenticate.
  • Grok Build. Clone the repository into ~/.grok/plugins/corebee, open /plugins and enable Corebee, then finish the sign-in in your browser.
  • Any other MCP client. Skip the plugin and point the client at the endpoint above with OAuth. The plugin only adds the skills and the rule on top of the same server.

Corebee's first-party Cursor Marketplace submission is in review and is not listed there yet. Grok Bot installs from that same marketplace, so Corebee is not available in Grok Bot yet either.

Tool discovery

tools/list returns the full list of 44 tools in every session. A Meta Muse connection lists up to 24 tools: only those its granted scopes allow (14 read tools with Read only). No extra discovery step is needed.

Tools by scope

Each tool requires the OAuth scope shown. Every tool your connection can use appears in tools/list (a Meta Muse connection sees only the Muse tool set), but a call fails unless the token was granted that scope. A Meta Muse connection lists up to 24 tools: only those its granted scopes allow (14 read tools with Read only).Scopes also follow your role in the workspace: agents cannot be granted settings changes or deletes, and viewers are read-only.

Conversations

conversations:read, conversations:write

Read, reply to, and manage support conversations in the inbox.

list_conversationsconversations:read
get_conversationconversations:read
bulk_export_conversationsconversations:read
reply_to_conversationconversations:write
add_conversation_noteconversations:write
assign_conversationconversations:write
close_conversationconversations:write
reopen_conversationconversations:write
set_priorityconversations:write
add_labelconversations:write
bulk_close_conversationsconversations:write
bulk_snooze_conversationsconversations:write
bulk_tag_with_sentimentconversations:write
bulk_add_noteconversations:write

Contacts

contacts:read, contacts:write, contacts:delete

Manage customer contact records and notes.

list_contactscontacts:read
get_contactcontacts:read
create_contactcontacts:write
update_contactcontacts:write
add_contact_notecontacts:write
delete_contactcontacts:delete
bulk_delete_contactscontacts:delete

Knowledge

knowledge:read, knowledge:write, knowledge:delete

Search and maintain the AI knowledge base that grounds answers, and ask the specialist agents that read it.

list_knowledge_sourcesknowledge:read
get_knowledge_sourceknowledge:read
search_knowledgeknowledge:read
a2a_action_agentknowledge:read
a2a_diagnostic_agentknowledge:read
a2a_escalation_agentknowledge:read
a2a_knowledge_agentknowledge:read
add_knowledge_urlknowledge:write
update_knowledge_sourceknowledge:write
delete_knowledge_sourceknowledge:delete

Metrics

metrics:read

Read analytics and performance reports (read-only).

get_metricsmetrics:read
get_agent_performancemetrics:read
get_channel_analyticsmetrics:read
export_reportmetrics:read
get_trendsmetrics:read
export_report_taskmetrics:read

Settings

settings:read, settings:write

Read organization configuration, list chat widgets, and change a widget's appearance and behavior. Pass widget_id when the workspace has more than one widget.

get_widget_settingssettings:read
list_widgetssettings:read
list_team_memberssettings:read
get_organization_settingssettings:read
update_widget_settingssettings:write
configure_widget_appearancesettings:write
configure_widget_behaviorsettings:write

Deletes and replies

  • Delete tools never delete on the first call: it returns a preview and a confirm_token, and the delete runs only when the same call is repeated with that token after the user approves (valid 5 minutes, single use).
  • Deleting a contact removes the contact, its notes and what the AI remembers about it. Its conversations and messages are kept, no longer linked to a contact.
  • reply_to_conversation sends through the same path as the Corebee inbox, and its result says whether the reply was handed to the channel (delivered true or false). A later bounce is not reflected, and phone conversations cannot receive a typed reply. It sends at once; Corebee does not hold replies for approval. For a note only your team sees, use add_conversation_note.

Access modes

When an app other than Corebee's own Claude connector asks for any change or delete permission, the Corebee consent screen offers two choices:

  • Read only. The app gets only read permissions. It cannot reply, change or delete anything, whatever else it asked for.
  • Read and make changes. Selected by default. Each change permission is a checkbox, ticked by default; untick any you do not want. Delete permissions stay off unless you tick them. A Meta Muse connection is never offered delete permissions.

A token never gets more than you approved and your role allows. To change the choice later, revoke the app under Connected apps and connect again.

Tools available in Meta Muse

A Meta Muse connection sees and can call these 24 tools only. A call to any other tool returns an error. A Meta Muse connection lists up to 24 tools: only those its granted scopes allow (14 read tools with Read only). Each tool is documented in full below. Tools for other clients follow under Other clients only.

Scopes requested by Muse

A Muse connection can hold only these scopes, whatever it asks for. It never gets delete scopes or settings changes, and it gets no more than you approve and your role allows:

  • conversations:read
  • conversations:write
  • contacts:read
  • contacts:write
  • knowledge:read
  • knowledge:write
  • metrics:read
  • settings:read

Muse has no delete tools. Pages added through Muse are removed in the Corebee app, under Knowledge.

A Sensitive write sends to a customer, changes what your AI agent tells customers, deletes, makes a bulk change or changes the chat widget. A Write makes any other change. Updating the status shown in an open web chat window is not a send. A Read changes nothing.

list_conversations

ReadIn Meta Muse

Lists the workspace inbox, most recent activity first, 50 per page, with each customer’s latest message.

Scope
conversations:read
Inputs
  • status (one of: open, resolved, pending, snoozed, all, optional): Filter by conversation status. Defaults to "open".
  • page (number, optional): Page number for pagination, starting at 1.
  • assignee_id (string, optional): Filter by assigned team member: member_id from list_team_members.
  • priority (one of: low, medium, high, urgent, none, optional): Filter by priority. "none" matches conversations whose priority was never set.
  • contact_id (integer, optional): Filter by customer: a contact id from list_contacts or get_contact.
Returns
conversations (id, status, priority, assignee member_id, contact (id, name, email), channel, subject, created_at, last_activity_at, last_customer_message_preview of up to 140 characters and last_customer_message_at), page, limit and has_more. channel: where reply_to_conversation sends (web_widget for web chat, email, sms, whatsapp, phone and others). subject: the email subject, or null. Filters: status, assignee_id, priority and contact_id. There is no text search: find the contact with list_contacts and filter by contact_id.
Side effects
None. Reads only.
Values
Conversation status: open, pending, resolved, snoozed. The status filter also takes all. Priority: low, medium, high, urgent, or none (never set or cleared).
Rate limit
No per-tool limit.

get_conversation

ReadIn Meta Muse

Reads one conversation with its newest messages, 50 at a time, including internal notes.

Scope
conversations:read
Inputs
  • conversation_id (string, required): The conversation ID to retrieve.
  • before (string, optional): Return messages older than this cursor: a message id (use next_before from the previous page) or an ISO 8601 timestamp. Omit for the newest messages.
Returns
The conversation (id, status, priority, assignee member_id, channel, subject, dates), its contact, messages oldest first (each with sender_type, content, is_private and created_at), has_more and next_before for the previous page. channel: where reply_to_conversation sends (web_widget for web chat, email, sms, whatsapp, phone and others).
Side effects
None. Reads only.
Values
Conversation status: open, pending, resolved, snoozed.
Rate limit
No per-tool limit.

reply_to_conversation

Sensitive writeIn Meta Muse

Sends a reply to the customer on the conversation’s own channel (email, SMS, WhatsApp, web chat and others), as the signed-in team member.

Scope
conversations:write
Inputs
  • conversation_id (string, required): The conversation ID to reply to.
  • content (string, required): The message content to send.
  • idempotency_key (string, optional): Optional key (max 64 chars). Retrying with the same key never sends the reply twice.

Other clients also see: private. See Side effects.

Returns
success, message_id, created_at, conversation_id, delivered (true when the channel accepted the reply), channel, and a reason when delivered is false.
Side effects
Sends the message to the customer as soon as it is called; Corebee does not hold it for approval. Saves it in the conversation, fires the message.sent webhook, and stops the AI agent answering in a conversation handed off to a person. A sent reply cannot be recalled. Other clients also see a private input (kept for older clients): private=true saves an internal note instead and sends nothing. A Meta Muse connection does not see it and uses add_conversation_note for notes.
Values
delivered: true, false, or null for a replayed idempotency_key.
Rate limit
30 calls a minute per workspace, shared by reply_to_conversation and add_conversation_note.

add_conversation_note

WriteIn Meta Muse

Adds an internal note to a conversation for the team.

Scope
conversations:write
Inputs
  • conversation_id (string, required): The conversation ID to add the note to.
  • content (string, required): The note text. Only your team sees it.
  • idempotency_key (string, optional): Optional key (max 64 chars). Retrying with the same key never saves the note twice.
Returns
success, message_id, created_at, conversation_id, private: true and delivered: false.
Side effects
Saves a private message in the conversation, attributed to you. The customer never sees it, nothing is sent on any channel and no webhook fires.
Rate limit
30 calls a minute per workspace, shared by reply_to_conversation and add_conversation_note.

assign_conversation

WriteIn Meta Muse

Assigns a conversation to a team member, or unassigns it.

Scope
conversations:write
Inputs
  • conversation_id (string, required): The conversation ID to assign.
  • assignee_id (string or null, required): The member_id to assign to (from list_team_members), or null to unassign.
Returns
success, conversation_id and assignee_id (a member_id, or null).
Side effects
Uses the Corebee inbox assign path. Changes the assignee and last_activity_at, adds a private "assigned" line to the conversation timeline and records it in the audit log. The new assignee gets an in-app notification, unless they assigned themselves or turned assignment notifications off. Viewers and members who cannot see the conversation cannot be assigned. Nothing is sent to the customer and no webhook fires.
Rate limit
No per-tool limit.

close_conversation

WriteIn Meta Muse

Marks a conversation as resolved.

Scope
conversations:write
Inputs
  • conversation_id (string, required): The conversation ID to close.
Returns
success, conversation_id, status: resolved and changed (false when it was already resolved).
Side effects
Uses the Corebee inbox status path. Sets the status to resolved and updates last_activity_at, adds a private "resolved" line to the timeline, closes any open escalations on the conversation, fires the conversation.updated webhook and runs Corebee’s usual after-resolve processing (such as quality scoring). No message is sent to the customer. An open web chat window shows the new status (and the rating survey only if the workspace turned it on). Nothing is delivered to the customer by email, SMS or other channels. Calling it again changes nothing.
Values
Conversation status: open, pending, resolved, snoozed.
Rate limit
No per-tool limit.

reopen_conversation

WriteIn Meta Muse

Reopens a resolved, pending or snoozed conversation.

Scope
conversations:write
Inputs
  • conversation_id (string, required): The conversation ID to reopen.
Returns
success, conversation_id, status: open and changed (false when it was already open).
Side effects
Uses the Corebee inbox status path. Sets the status to open, clears any snooze, updates last_activity_at, adds a private "reopened" line to the timeline and fires the conversation.updated webhook. No message is sent to the customer. An open web chat window shows the new status. Nothing is delivered to the customer by email, SMS or other channels. Calling it again changes nothing.
Values
Conversation status: open, pending, resolved, snoozed.
Rate limit
No per-tool limit.

set_priority

WriteIn Meta Muse

Sets or clears a conversation’s priority.

Scope
conversations:write
Inputs
  • conversation_id (string, required): The conversation ID.
  • priority (one of: low, medium, high, urgent, none, required): One of low, medium, high, urgent, or none to clear the priority.
Returns
success, conversation_id and the new priority (none when cleared).
Side effects
Changes the priority and last_activity_at. none clears the priority, as the inbox priority menu does. Nothing is sent to the customer.
Values
Priority: low, medium, high, urgent, none.
Rate limit
No per-tool limit.

list_contacts

ReadIn Meta Muse

Lists contacts, 50 per page, optionally searched by name or email.

Scope
contacts:read
Inputs
  • search (string, optional): Search query to filter contacts by name or email.
  • page (number, optional): Page number for pagination, starting at 1.
Returns
contacts (id, name, email, phone_number, created_at, last_activity_at), total, page, limit and has_more.
Side effects
None. Reads only.
Rate limit
No per-tool limit.

get_contact

ReadIn Meta Muse

Reads one contact with up to 10 recent conversations and up to 5 recent notes.

Scope
contacts:read
Inputs
  • contact_id (integer, required): The contact ID to retrieve.
Returns
The contact (name, email, phone_number, identifier, custom and additional attributes, dates), up to 10 recent conversations (id, status, subject, dates), newest activity first, and up to 5 notes, newest first. Deleted contacts and conversations are not shown.
Side effects
None. Reads only.
Values
Conversation status: open, pending, resolved, snoozed.
Rate limit
No per-tool limit.

create_contact

WriteIn Meta Muse

Creates a contact. At least one of name, email or phone_number is needed.

Scope
contacts:write
Inputs
  • name (string, optional): Full name of the contact.
  • email (string, optional): Email address of the contact.
  • phone_number (string, optional): Phone number of the contact.
  • identifier (string, optional): External identifier for the contact (e.g., customer ID from another system).
  • custom_attributes (object, optional): Custom attributes as key-value pairs.
Returns
success and the new contact.
Side effects
Adds a contact record. Nothing is sent to the contact.
Rate limit
No per-tool limit.

update_contact

WriteIn Meta Muse

Changes the fields you pass on an existing contact: name, email, phone number, identifier and custom attributes.

Scope
contacts:write
Inputs
  • contact_id (integer, required): The contact ID to update.
  • name (string, optional): New name for the contact.
  • email (string, optional): New email address for the contact.
  • phone_number (string, optional): New phone number for the contact.
  • identifier (string, optional): New external identifier for the contact.
  • custom_attributes (object, optional): Custom attributes to update (will be merged with existing).

Other clients also see: blocked. See Side effects.

Returns
success and the updated contact.
Side effects
Updates the contact record. Nothing is sent to the contact. Other clients also see a blocked input: it is a record flag only and does not stop messages from the contact or AI replies to them. A Meta Muse connection does not see it.
Rate limit
No per-tool limit.

add_contact_note

WriteIn Meta Muse

Adds an internal note to a contact, up to 5000 characters.

Scope
contacts:write
Inputs
  • contact_id (integer, required): The contact ID to add a note to.
  • content (string, required): The note content, up to 5000 characters.
Returns
success and the saved note.
Side effects
Saves a note only team members see, attributed to you. Nothing is sent to the contact.
Rate limit
No per-tool limit.

list_knowledge_sources

ReadIn Meta Muse

Lists the knowledge base sources (web pages, documents, articles) with their status.

Scope
knowledge:read
Inputs
  • type (one of: url, file, manual, faq, all, optional): Filter by source type. Defaults to "all".
Returns
sources (id, name, type, status, source_url, error, chunks_count, dates), total and has_more. Up to 50.
Side effects
None. Reads only.
Values
Source status: pending, processing, completed, completed_partial, failed.
Rate limit
No per-tool limit.

add_knowledge_url

Sensitive writeIn Meta Muse

Adds one web page to the knowledge base. Only that page is indexed, not the rest of the site.

Scope
knowledge:write
Inputs
  • url (string, required): The URL to add as a knowledge source.
  • name (string, optional): A friendly name for this source. Defaults to the URL.
Returns
success and the new source (id, name, url, status: pending).
Side effects
Publishes the page's content to your AI agent: once indexed (usually within minutes) the agent uses it when answering customers on every channel, with no review step. Any public URL is accepted. The page is fetched from the public web, possibly through a listed sub-processor such as the Jina AI web reader. To remove it, delete the source in Corebee under Knowledge. Pages added through Meta Muse are removed in the Corebee app the same way.
Values
Source status: pending, processing, completed, completed_partial, failed.
Rate limit
10 calls a minute per workspace, shared by add_knowledge_url and update_knowledge_source.

get_knowledge_source

ReadIn Meta Muse

Reads one knowledge source with its processing status and chunk count.

Scope
knowledge:read
Inputs
  • source_id (string, required): The knowledge source ID to retrieve.
Returns
The source’s details, status, error message if any, chunk count and dates.
Side effects
None. Reads only.
Values
Source status: pending, processing, completed, completed_partial, failed.
Rate limit
No per-tool limit.

search_knowledge

ReadIn Meta Muse

Finds knowledge base passages that contain a word or short phrase, matched literally.

Scope
knowledge:read
Inputs
  • query (string, required): The search query to find in knowledge content.
  • limit (number, optional): Maximum number of results to return (default 10, max 50).
  • source_id (string, optional): Filter results to a specific knowledge source.
Returns
query, results_count and results (chunk_id, content_preview, chunk_index, source id, name, type and url).
Side effects
None. Reads only.
Rate limit
No per-tool limit.

a2a_knowledge_agent

ReadIn Meta Muse

Answers a question in plain words from the workspace’s own knowledge base: an AI model writes a short answer using only the passages it finds.

Scope
knowledge:read
Inputs
  • question (string, required): The question to answer from your knowledge base.
  • history (array of object, optional): Optional recent turn history. Omit on a cold delegation; the callee will not fabricate history.

Other clients also see: task_description, context. See Side effects.

Returns
specialist (always knowledge), answered (false when nothing relevant was found), response (the answer text, empty when answered is false), confidence (0 to 1), sources (names or URLs of the passages used), actions (always empty), should_escalate (always false) and processing_time_ms. When the search could not run (an error or a timeout), the call returns an error instead, so it is never mistaken for "nothing found". A Meta Muse connection passes question and optional history; other clients pass task_description, and the context input is not used by this tool.
Side effects
None in the workspace. The question and the passages found are sent to an AI model sub-processor to write the answer.
Rate limit
30 calls a minute per workspace.

get_metrics

ReadIn Meta Muse

Reads dashboard numbers for a period.

Scope
metrics:read
Inputs
  • period (one of: today, this_week, this_month, last_30_days, optional): Time period for metrics. Defaults to "this_week".
Returns
Conversation counts by status, total and new contacts, total and AI messages, knowledge source counts, CSAT (average and number of responses, or null) and average first-response time (or null).
Side effects
None. Reads only.
Rate limit
No per-tool limit.

get_agent_performance

ReadIn Meta Muse

Reads per-member stats for a period: assigned, resolved and resolution rate.

Scope
metrics:read
Inputs
  • period (one of: today, this_week, this_month, last_30_days, optional): Time period for metrics. Defaults to "this_week".
  • agent_id (string, optional): Organization member ID (member_id from list_team_members).
Returns
period, period_start and agents (member_id, name, email, role, and stats: conversations_assigned, conversations_resolved, resolution_rate).
Side effects
None. Reads only.
Rate limit
No per-tool limit.

get_channel_analytics

ReadIn Meta Muse

Reads conversation and message counts per channel for a period.

Scope
metrics:read
Inputs
  • period (one of: today, this_week, this_month, last_30_days, optional): Time period for analytics. Defaults to "this_week".
Returns
period, period_start, totals and channels (one entry per channel with its stats).
Side effects
None. Reads only.
Rate limit
No per-tool limit.

export_report

ReadIn Meta Muse

Builds a report for a period. "summary" gives counts only. "json" gives up to 100 recent conversation and contact rows, and needs conversations:read or contacts:read for those rows.

Scope
metrics:read
Inputs
  • report_type (one of: conversations, contacts, metrics, full, required): Type of report to generate.
  • period (one of: today, this_week, this_month, last_30_days, all_time, optional): Time period for the report. Defaults to "this_week".
  • format (one of: json, summary, optional): "summary" (default): counts only, no personal data. "json": up to 100 most recent rows per section plus _row_limits totals.
Returns
report_type, period, generated_at and the conversations, contacts and metrics sections. json adds _row_limits and _truncated, and its conversation rows give status and priority as list_conversations does (status open, resolved, pending or snoozed; priority none when unset). _notes says when a section fell back to counts for lack of a scope.
Side effects
None. Reads only.
Values
Conversations by status: open, pending, resolved, snoozed. Contacts by type: visitor, lead, customer.
Rate limit
No per-tool limit.

list_team_members

ReadIn Meta Muse

Lists the workspace members with the member_id other tools take.

Scope
settings:read
Inputs
  • role (one of: owner, agent, viewer, all, optional): Filter by role: owner, agent or viewer (the only roles a workspace stores). Defaults to "all".
Returns
members (member_id, name, email, role, availability, avatar_url, joined_at), total and has_more. Up to 50.
Side effects
None. Reads only.
Values
Role: owner, agent or viewer (the only roles a workspace stores).
Rate limit
No per-tool limit.

Other clients only

These tools are listed for other clients, such as Claude, ChatGPT, Cursor and API keys. A Meta Muse connection does not see them; its tools are documented above. A Sensitive write sends to a customer, changes what your AI agent tells customers, deletes, makes a bulk change or changes the chat widget. A Write makes any other change. Updating the status shown in an open web chat window is not a send. A Read changes nothing.

add_label

Write

Adds an existing label (by its UUID) to a conversation.

Scope
conversations:write
Inputs
  • conversation_id (string, required): The conversation ID.
  • label_id (string or number, required): The ID of the label to add (a UUID).
Returns
success, conversation_id and label_id (already_exists: true when the label was already on it).
Side effects
Links the label to the conversation. Nothing is sent to the customer.
Rate limit
No per-tool limit.

bulk_close_conversations

Sensitive write

Resolves up to 25 conversations in one call.

Scope
conversations:write
Inputs
  • conversation_ids (array of string (max 25), required): Conversation IDs to close (max 25).
Returns
success, processed (how many of the IDs were found in this workspace and closed) and their conversation_ids.
Side effects
Sets each conversation to resolved. This tool sends no message.
Values
Conversation status: open, pending, resolved, snoozed.
Rate limit
5 calls a minute per workspace, shared by all bulk_* tools. Up to 25 items per call.

bulk_snooze_conversations

Sensitive write

Snoozes up to 25 conversations until one wake time.

Scope
conversations:write
Inputs
  • conversation_ids (array of string (max 25), required): Conversation IDs to snooze (max 25).
  • until (string, required): ISO 8601 datetime or "tomorrow_morning" / "next_week".
Returns
success, snoozed_until, processed and the conversation_ids that were snoozed.
Side effects
Sets each conversation to snoozed until the wake time.
Values
Conversation status: open, pending, resolved, snoozed.
Rate limit
5 calls a minute per workspace, shared by all bulk_* tools. Up to 25 items per call.

bulk_tag_with_sentiment

Sensitive write

Attaches one sentiment label to up to 25 conversations.

Scope
conversations:write
Inputs
  • conversation_ids (array of string (max 25), required): Conversation IDs to tag (max 25).
  • sentiment (one of: positive, neutral, negative, frustrated, happy, required): Sentiment to attach.
Returns
success, sentiment and processed (how many conversations were tagged).
Side effects
Adds the sentiment label to each conversation.
Values
Sentiment: positive, neutral, negative, frustrated, happy.
Rate limit
5 calls a minute per workspace, shared by all bulk_* tools. Up to 25 items per call.

bulk_export_conversations

Read

Exports up to 25 chosen conversations as CSV text.

Scope
conversations:read
Inputs
  • conversation_ids (array of string (max 25), required): Conversation IDs to export (max 25).
Returns
success, row_count and csv (the CSV text).
Side effects
None. Reads only.
Rate limit
5 calls a minute per workspace, shared by all bulk_* tools. Up to 25 items per call.

bulk_add_note

Sensitive write

Adds the same internal note to up to 25 conversations.

Scope
conversations:write
Inputs
  • conversation_ids (array of string (max 25), required): Conversation IDs (max 25).
  • note (string, required): Note content.
Returns
success and processed (how many notes were saved).
Side effects
Saves a private note in each conversation. Customers never see it.
Rate limit
5 calls a minute per workspace, shared by all bulk_* tools. Up to 25 items per call.

delete_contact

Sensitive write

Permanently deletes one contact.

Scope
contacts:delete
Inputs
  • contact_id (integer, required): The contact ID to delete.
  • confirm_token (string, optional): Token from the preview returned by the first call. Pass it only after the user has approved the preview.
Returns
First call: a preview and confirm_token. Confirmed call: deleted: true, the deleted contact’s id, name and email, and how many linked conversations were kept.
Side effects
Deletes the contact, its notes, channel identities and saved AI memory. Its conversations and messages are kept without a linked contact. This cannot be undone. The first call deletes nothing and returns a preview and a confirm_token. The delete runs only when the same call is repeated with that token (valid 5 minutes, single use). The hosted endpoint always uses this two-call flow.
Rate limit
10 calls a minute per workspace for this tool.

bulk_delete_contacts

Sensitive write

Permanently deletes up to 25 contacts in one call.

Scope
contacts:delete
Inputs
  • contact_ids (array of string or number (max 25), required): Contact IDs to delete (max 25).
  • confirm_token (string, optional): Token from the preview returned by the first call. Pass it only after the user has approved the preview.
Returns
First call: a preview and a confirm_token bound to exactly these IDs. Confirmed call: deleted: true, processed, requested and how many linked conversations were kept.
Side effects
Deletes each contact with its notes, channel identities and saved AI memory. Conversations and messages are kept. This cannot be undone. The first call deletes nothing and returns a preview and a confirm_token. The delete runs only when the same call is repeated with that token (valid 5 minutes, single use). The hosted endpoint always uses this two-call flow.
Rate limit
5 calls a minute per workspace, shared by all bulk_* tools. Up to 25 items per call.

update_knowledge_source

Sensitive write

Renames a knowledge source or changes its URL.

Scope
knowledge:write
Inputs
  • source_id (string, required): The knowledge source ID to update.
  • name (string, optional): New name for the knowledge source.
  • source_url (string, optional): New URL for the knowledge source (only for URL type sources). Will trigger re-processing.
Returns
success, the updated source and reprocessing (true when the URL changed).
Side effects
Updates the source. A new URL sets it back to pending and indexes the new page, and the AI agent then uses that content when answering customers, with no review step.
Values
Source status: pending, processing, completed, completed_partial, failed.
Rate limit
10 calls a minute per workspace, shared by add_knowledge_url and update_knowledge_source.

delete_knowledge_source

Sensitive write

Permanently deletes a knowledge source and everything indexed from it.

Scope
knowledge:delete
Inputs
  • source_id (string, required): The knowledge source ID to delete.
  • confirm_token (string, optional): Token from the preview returned by the first call. Pass it only after the user has approved the preview.
Returns
First call: a preview and confirm_token. Confirmed call: deleted: true with the source id and name.
Side effects
Deletes the source, its chunks, scan history, tags, version history and citation records. Knowledge gaps that pointed at it are kept. This cannot be undone. The first call deletes nothing and returns a preview and a confirm_token. The delete runs only when the same call is repeated with that token (valid 5 minutes, single use). The hosted endpoint always uses this two-call flow.
Rate limit
10 calls a minute per workspace for this tool.

update_widget_settings

Sensitive write

Changes a chat widget’s color, welcome title, reply time or pre-chat form switch.

Scope
settings:write
Inputs
  • widget_id (integer or string, optional): Widget to act on (widget_id from list_widgets). Optional when the workspace has exactly one widget.
  • widget_color (string, optional): Primary widget color as hex (e.g. "#1a73e8").
  • welcome_title (string, optional): Welcome screen title text.
  • reply_time (one of: in_a_few_minutes, in_a_few_hours, in_a_day, optional): Expected reply time shown to customers.
  • pre_chat_form_enabled (boolean, optional): Whether to show a pre-chat form collecting info before conversation starts.
Returns
success and the updated settings.
Side effects
Changes the chat widget customers see on your live website as soon as it is saved. Pass widget_id when the workspace has more than one widget (list_widgets).
Rate limit
No per-tool limit.

get_widget_settings

Read

Reads a chat widget’s appearance, behavior and pre-chat form settings.

Scope
settings:read
Inputs
  • widget_id (integer or string, optional): Widget to act on (widget_id from list_widgets). Optional when the workspace has exactly one widget.
Returns
The widget configuration.
Side effects
None. Reads only.
Rate limit
No per-tool limit.

list_widgets

Read

Lists the chat widgets in the workspace.

Scope
settings:read
Inputs
None.
Returns
widgets (widget_id, is_default, website_url, created_at) and total.
Side effects
None. Reads only.
Rate limit
No per-tool limit.

configure_widget_appearance

Sensitive write

Changes a chat widget’s color, welcome title, logo or position.

Scope
settings:write
Inputs
  • widget_id (integer or string, optional): Widget to act on (widget_id from list_widgets). Optional when the workspace has exactly one widget.
  • widget_color (string, optional): Primary widget color as hex (e.g. "#1a73e8").
  • welcome_title (string, optional): Welcome screen title text.
  • logo_url (string, optional): URL to the company logo to display in the widget.
  • position (one of: left, right, optional): Widget position on the page (left or right).
Returns
success and the updated appearance.
Side effects
Changes the chat widget customers see on your live website as soon as it is saved. Pass widget_id when the workspace has more than one widget (list_widgets).
Rate limit
No per-tool limit.

configure_widget_behavior

Sensitive write

Changes a chat widget’s reply time and pre-chat form. AI answer settings are not changed.

Scope
settings:write
Inputs
  • widget_id (integer or string, optional): Widget to act on (widget_id from list_widgets). Optional when the workspace has exactly one widget.
  • reply_time (one of: in_a_few_minutes, in_a_few_hours, in_a_day, optional): Expected reply time shown to customers.
  • pre_chat_form_enabled (boolean, optional): Whether to show a pre-chat form collecting info before conversation starts.
  • pre_chat_form_options (object, optional): Pre-chat form configuration options.
Returns
success and the updated behavior.
Side effects
Changes the chat widget customers see on your live website as soon as it is saved. Pass widget_id when the workspace has more than one widget (list_widgets).
Rate limit
No per-tool limit.

get_organization_settings

Read

Reads the workspace settings, including plan, status and AI settings.

Scope
settings:read
Inputs
None.
Returns
The organization’s plan, status, AI settings and configuration.
Side effects
None. Reads only.
Rate limit
No per-tool limit.

export_report_task

Read

Runs the export_report "summary" counts in the background. Never returns rows or personal data.

Scope
metrics:read
Inputs
  • report_type (one of: conversations, contacts, metrics, full, required): Type of report to generate.
  • period (one of: today, this_week, this_month, last_30_days, all_time, optional)
  • format (one of: json, summary, optional): Accepted for compatibility; the async task always returns the "summary" counts. Use export_report with format "json" for rows.
Returns
A task_id at once. Poll tasks/get until the state is completed or failed, then read tasks/result.
Side effects
Creates a background task record. No workspace data changes.
Values
Task state: working, input_required, completed, failed, cancelled.
Rate limit
30 task starts a minute per credential, shared by all task-backed tools.

a2a_action_agent

Read

Suggests one inbox action for a task. Nothing is executed.

Scope
knowledge:read
Inputs
  • task_description (string, required): Plain-language description of what the specialist should do. Acts as the "message" the specialist receives.
  • context (object, optional): Optional structured context: conversation/customer IDs, current page, free-form metadata.
  • history (array of object, optional): Optional recent turn history. Omit on a cold delegation; the callee will not fabricate history.
Returns
The suggested action with the fields it could fill, or answered=false.
Side effects
None. Reads only. Uses fixed keyword rules, no AI model, and reads no workspace data.
Rate limit
No per-tool limit.

a2a_diagnostic_agent

Read

Matches a problem description to generic causes and steps for six areas.

Scope
knowledge:read
Inputs
  • task_description (string, required): Plain-language description of what the specialist should do. Acts as the "message" the specialist receives.
  • context (object, optional): Optional structured context: conversation/customer IDs, current page, free-form metadata.
  • history (array of object, optional): Optional recent turn history. Omit on a cold delegation; the callee will not fabricate history.
Returns
Possible causes, suggested steps and a follow-up question, or a request for more detail.
Side effects
None. Reads only. Uses fixed keyword rules, no AI model, and reads no workspace data.
Rate limit
No per-tool limit.

a2a_escalation_agent

Read

Checks a customer message for a request to reach a person, frustration or a repeated issue.

Scope
knowledge:read
Inputs
  • task_description (string, required): Plain-language description of what the specialist should do. Acts as the "message" the specialist receives.
  • context (object, optional): Optional structured context: conversation/customer IDs, current page, free-form metadata.
  • history (array of object, optional): Optional recent turn history. Omit on a cold delegation; the callee will not fabricate history.
Returns
On a match, a handoff reply and a suggested escalate_to_human action with a priority.
Side effects
None. Reads only. It does not hand off the conversation or notify anyone. Uses fixed keyword rules, no AI model, and reads no workspace data.
Rate limit
No per-tool limit.

Errors

  • HTTP 401 with a WWW-Authenticate header pointing at /.well-known/oauth-protected-resource: the token is missing, invalid, expired or revoked, or the user left the workspace. Refresh the token or sign in again.
  • HTTP 503 with no WWW-Authenticate header: Corebee could not check the token right now. Keep the token and retry.
  • Tool errors come back as a normal result with isError: true and a text message:
    • Insufficient permissions. Required scope: ... when the token was not granted that scope.
    • A rate limit message when a throttled tool is called too often. Wait a minute and retry.
    • Could not ... . Try again; if it repeats, contact support@corebee.ai. when Corebee could not finish a read or change, for example Could not close the conversation. Try again; if it repeats, contact support@corebee.ai. The message is fixed. The underlying reason is logged on our side and never shown, so it cannot leak internal details.
    • ... not found. when the ID does not exist in this workspace.
    • The tool "..." is not available to this connection. when a Meta Muse connection calls a tool outside its set.
    • Tool '...' timed out after ...ms when a call runs too long. For a reply or note, check get_conversation before retrying, or retry with the same idempotency_key.
  • Delete tools answer the first call with a preview and a confirm_token instead of deleting. Repeat the same call with that token within 5 minutes to delete. An expired, reused or mismatched token is refused.

Connected apps and revoking access

  • Apps you sign in to with Corebee, such as Claude, Meta Muse or Cursor, are listed in Corebee under Settings → Login & security → Connected apps. Every member can open that page and sees the apps they connected. Workspace owners also see the apps their team connected.
  • Revoke an app there to end its access. Its tokens stop working within about a minute, and the app has to ask you to sign in again. Revoking does not delete data the app already received.
  • An app never has more access than your role. If you are removed from the workspace, apps you connected lose access to it.
  • API keys are separate: an owner revokes them under Settings → Developer API.

Example prompts

Once connected, ask your MCP client in plain language. It will pick the right tools automatically.

“Show me the 5 most recent open conversations and summarize what each customer wants.”

Expected: Calls list_conversations, then get_conversation on each, and returns a short summary per thread.

“A customer is asking about our refund window. Search the knowledge base and draft a reply.”

Expected: Calls search_knowledge for the refund policy and drafts a grounded answer. It calls reply_to_conversation, which sends the reply to the customer, only after you approve the text.

“What is our CSAT and average first-response time over the last 30 days?”

Expected: Calls get_metrics with period last_30_days. CSAT is shown as not available when no survey responses were recorded.

“Which channels did customers contact us on in the last 30 days?”

Expected: Calls get_channel_analytics with period last_30_days and lists conversations per channel; no writes.

“Add https://corebee.ai/contact to my Corebee knowledge base.”

Expected: Calls add_knowledge_url, which indexes only that page, not the rest of the site, and returns a pending source. Indexing runs in the background; list_knowledge_sources shows the status.

Limitations

  • A token is scoped to exactly one organization, the one Corebee opens when you sign in.
  • Tools are gated by granted scopes. A read-only token cannot reply, delete, or change settings.
  • Transport is Streamable HTTP only. The legacy SSE endpoint is deprecated and will be removed.
  • This endpoint does not send requests back to your client, so MCP sampling and elicitation are not used here. Delete tools always use the two-call confirm_token flow.
  • Access tokens last 1 hour; clients must refresh. Only PKCE S256 is accepted (no plain).
  • Some tools are throttled per workspace: replies and notes (30 a minute), the knowledge agent (30 a minute), adding or changing a knowledge source (10 a minute, add_knowledge_url and update_knowledge_source together), deletes (10 a minute for delete_contact and delete_knowledge_source; bulk_delete_contacts shares the 5-a-minute bulk limit) and bulk actions (5 a minute). A throttled call returns an error; wait a minute and retry. Other tools have no per-tool limit. There is no global per-connection limit beyond the per-tool limits above.