Corebee MCP Server

The Corebee MCP server lets any Model Context Protocol client — Claude, an 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.

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:

Protected-resource discovery. On a 401 the client reads /.well-known/oauth-protected-resource (RFC 9728) to find the authorization server.
Dynamic Client Registration (DCR). The client registers itself at /api/v1/mcp/oauth/register (RFC 7591) — no manual client-id provisioning required.
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.
Token issuance. The token endpoint returns a short-lived, RS256-signed access token scoped to one organization and the scopes the user granted.

Authorization: Bearer <access_token>

Tool discovery

tools/list returns the full list of 42 tools in every session. No extra discovery step is needed.

Tools by scope

Each tool requires the OAuth scope shown. Every tool appears in the list, but a call fails unless the token was granted that scope. 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

assign_conversationconversations:write

close_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.

Connected apps and revoking access

Apps you sign in to with Corebee, such as Claude 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 right away, and the app has to ask you to sign in again.
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 this week?”

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

“How many conversations did we resolve this week, and how does message volume compare with the last 30 days?”

Expected: Calls get_metrics for this week and get_trends for messages over the last 30 days; no writes.

“Add https://help.acme.com/returns as a knowledge source so the AI can answer returns questions.”

Expected: Calls add_knowledge_url, queues the page for ingestion, and confirms the new source.

Limitations

A token is scoped to exactly one organization. To operate across organizations, authorize once per organization.
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.
Access tokens are short-lived; clients must refresh. Only PKCE S256 is accepted (no plain).
Standard API rate limits apply; heavy bulk operations may be throttled.