MCP Server

Connect Claude, ChatGPT, Codex, Cursor and other MCP clients to your Chatbase workspace over OAuth.

The Chatbase MCP server lets an AI assistant work directly with your Chatbase workspace. It can list AI agents, manage the sources an AI agent is trained on, read conversations, and handle help desk tickets, without you copying data between tools.

It is a remote Model Context Protocol server. There is nothing to install or self-host.

Endpoint

https://mcp.chatbase.co/api/mcp

Authentication

OAuth 2.1, with no API key to create or paste

The endpoint is not a page to open in your browser. Add it to an MCP client, and the client opens the sign-in page for you.

Claude and ChatGPT

Chatbase is available as a connector. Install it in one click, then approve access when prompted.

Add to Claude

Works in Claude.ai and the Claude desktop app.

Add to ChatGPT

Works in ChatGPT on web and desktop.

If the connector is not available in your workspace, add it manually under Settings → Connectors → Add custom connector using the endpoint above.

On ChatGPT’s default Allow low-risk actions setting, the tools marked destructive are hidden rather than offered with a confirmation prompt. That covers deleting an AI agent or a source, and editing a source. If ChatGPT says it cannot delete or edit something, raise the permission setting for the connector.

Claude Code, Codex, Cursor and other clients

Point the client at the endpoint. Do not add an Authorization header. The client negotiates OAuth on its own and opens the sign-in page for you.

Claude Code

claude mcp add --transport http chatbase https://mcp.chatbase.co/api/mcp

Then run /mcp and choose Authenticate.

Or install the plugin, which bundles the server configuration and usage guidance:

claude plugin marketplace add Chatbase-co/chatbase-plugin
claude plugin install chatbase@chatbase

Codex

codex mcp add chatbase --url https://mcp.chatbase.co/api/mcp
codex mcp login chatbase

Or install the plugin:

codex plugin marketplace add Chatbase-co/chatbase-plugin
codex plugin add chatbase@chatbase

Cursor

Add the server under Settings → MCP → Add new MCP server, or edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "chatbase": {
      "type": "http",
      "url": "https://mcp.chatbase.co/api/mcp"
    }
  }
}

Other JSON clients

Most MCP clients, including VS Code, Windsurf, Zed and OpenCode, take the same shape:

{
  "mcpServers": {
    "chatbase": {
      "type": "http",
      "url": "https://mcp.chatbase.co/api/mcp"
    }
  }
}

If you already added chatbase manually, remove that entry before installing the plugin. A client will not show two servers with the same URL, so the plugin’s server appears to be missing when it is really a duplicate.

How sign-in works

1. Your client registers itself

   The first time a client connects, it registers with Chatbase automatically using Dynamic Client Registration. You do not create anything in advance.

2. You approve access in the browser

   Chatbase shows a consent screen listing the workspace and exactly which permissions the app is asking for. You choose the workspace and approve or deny.

3. The client receives a token

   Access is granted to that one client, for that one workspace, limited to the permissions you approved.

Chatbase never shows an app more than your own role allows. If you cannot delete sources, no app you approve can delete them either, even if it asks.

Token lifetime

Access token	Expires after 1 hour; the client refreshes it silently
Approval	Expires automatically after 90 days
Revocation	Takes effect immediately

Permissions

Chatbase groups permissions by resource and verb. An app requests a set, and on the consent screen you choose which of them to approve.

Resource	Read	Write	Delete	Export
AI agents	agents:read	agents:write	agents:delete	—
Sources	sources:read	sources:write	sources:delete	—
Conversations	chatlogs:read	chatlogs:write	chatlogs:delete	chatlogs:export
Help desk	helpdesk_tickets:read	helpdesk_tickets:write	helpdesk_tickets:delete	—

Delete and export permissions are shown on the consent screen but are not selected by default. Approve delete only if the app genuinely needs to remove data. Conversation search and export need chatlogs:export.

To give an app read-only access, approve only the read permissions.

A client only sees the tools its permissions cover. A short tool list usually means a narrow approval rather than a missing feature. Ask the assistant to call chatbase_whoami, which reports the workspace and the exact permissions in use.

What the assistant can do

The server exposes 27 tools: chatbase_whoami, which every connected app can call to report its own access, plus 26 grouped by area.

AI agents

List and inspect AI agents, create and clone them, update configuration, toggle auto-retrain, and send a chat message to an AI agent.

chatbase_list_agents · chatbase_get_agent · chatbase_create_agent · chatbase_clone_agent · chatbase_update_agent · chatbase_update_agent_auto_retrain · chatbase_delete_agent · chatbase_chat

Sources

Add, edit and remove the knowledge an AI agent is trained on. Every change takes effect immediately, with no separate training step.

chatbase_list_sources · chatbase_get_source · chatbase_get_sources_summary · chatbase_create_source · chatbase_update_source · chatbase_delete_source

Conversations

Search conversations by text and filters, export them for analysis, and update conversation metadata. Search takes up to 5 searches in one call.

chatbase_search_conversations · chatbase_export_conversations · chatbase_update_conversation

Help desk

Search, read and update tickets, post replies, and inspect teams and statuses.

chatbase_list_tickets · chatbase_search_tickets · chatbase_get_ticket · chatbase_create_ticket · chatbase_update_ticket · chatbase_list_ticket_messages · chatbase_create_ticket_message · chatbase_list_ticket_statuses · chatbase_list_helpdesk_teams

Two source operations cannot be undone. Deleting a source purges its knowledge straight away and nothing restores it. Re-creating the source afterwards starts from scratch. Editing a source overwrites its content and retrains it on the spot, so the previous text is gone. Both are marked destructive, so a well-behaved client will ask before running them.

Tool reference

Every tool except chatbase_whoami runs one Chatbase API operation, and its inputs and outputs are on the linked API reference page. chatbase_whoami takes no inputs and reports the workspace, the user and the permissions in use.

• Read returns data and changes nothing.
• Write creates or changes data in your workspace.
• Sensitive write reaches a real customer or can’t be undone. A client should ask you before every call.

Tool	Permission	Type	Side effects
chatbase_whoami	Always available	Read	—
chatbase_list_agents	agents:read	Read	—
chatbase_create_agent	agents:write	Write	Creates an AI agent. If you pass a URL, it also adds it as a link source and starts training. Counts toward your plan’s AI agent limit.
chatbase_get_agent	agents:read	Read	—
chatbase_update_agent	agents:write	Write	Changes the live AI agent’s settings. A list field replaces the stored list.
chatbase_delete_agent	agents:delete	Sensitive write	Deletes the AI agent and all its sources, and disconnects its integrations. Can’t be undone.
chatbase_update_agent_auto_retrain	sources:write	Write	Turns retraining every 7 days on or off.
chatbase_clone_agent	agents:write	Write	Creates a copy of the AI agent with its sources, except Notion sources. Counts toward your plan’s AI agent limit.
chatbase_chat	chatlogs:write	Write	Sends a message to the AI agent. Uses message credits, and the conversation appears in your logs.
chatbase_export_conversations	chatlogs:export	Read	—
chatbase_search_conversations	chatlogs:export	Read	—
chatbase_update_conversation	chatlogs:write	Sensitive write	Pauses, ends or resumes a live conversation. Pausing or ending stops the AI agent replying to a real person. On conversation-billing accounts an ended conversation can’t be resumed.
chatbase_get_sources_summary	sources:read	Read	—
chatbase_list_sources	sources:read	Read	—
chatbase_create_source	sources:write	Write	Adds a text, Q&A or link source and starts training it.
chatbase_get_source	sources:read	Read	—
chatbase_delete_source	sources:delete	Sensitive write	Removes the source’s knowledge from the AI agent immediately. Can’t be undone.
chatbase_update_source	sources:write	Sensitive write	Overwrites the source and retrains it. The previous content is gone.
chatbase_list_ticket_statuses	helpdesk_tickets:read	Read	—
chatbase_list_helpdesk_teams	helpdesk_tickets:read	Read	—
chatbase_create_ticket	helpdesk_tickets:write	Write	Creates a ticket for a customer. Your routing rules assign it unless you name an assignee.
chatbase_list_tickets	helpdesk_tickets:read	Read	—
chatbase_search_tickets	helpdesk_tickets:read	Read	—
chatbase_get_ticket	helpdesk_tickets:read	Read	—
chatbase_update_ticket	helpdesk_tickets:write	Sensitive write	Changes status, assignee, team or priority. Status and assignee changes run your help desk triggers, and closing a ticket can send the customer a satisfaction survey.
chatbase_list_ticket_messages	helpdesk_tickets:read	Read	—
chatbase_create_ticket_message	helpdesk_tickets:write	Sensitive write	Sends a reply the customer receives. It can also change the ticket’s status.

Limits

• The workspace needs the Standard plan or higher. On Free and Hobby plans, and on trials that signed up with a personal email address, every tool except chatbase_whoami returns an error.
• Each connection can make 1,000 requests every 10 seconds.
• Conversation search allows 10 searches per second per workspace.
• Lists are paginated. Conversation export returns up to 20 conversations per call.

Errors

A failed tool call returns a tool error whose text starts with the error code, for example SUBSCRIPTION_API_RESTRICTED_PLAN: A Standard plan or higher is required to access the API. The codes and recovery steps are the same as the API’s, listed in Error handling.

Two errors come from the MCP endpoint itself, before any tool runs:

Status	Code	Meaning
401	AUTH_INVALID_TOKEN	The token is missing, expired or revoked. The WWW-Authenticate header points the client to sign-in.
429	RATE_LIMIT_TOO_MANY_REQUESTS	The connection went over its rate limit. Retry after the number of seconds in Retry-After.

Manage connected apps

Every app you approve appears in your workspace under Settings → General → Connected apps, showing what it can access and when it last obtained a token.

Select Revoke to cut off access. It takes effect on the app’s very next request, even if its current token has not expired. The app must ask for your approval again before it can reconnect.

An app’s name is chosen by the app itself when it registers, and Chatbase cannot verify it. Treat the name as a label, not as proof of identity, and revoke anything you do not recognise.

Troubleshooting

The client says the server needs authentication

Expected before you sign in. Trigger your client’s authentication step (/mcp in Claude Code, codex mcp login chatbase in Codex) and approve the consent screen.

The server does not appear after installing the plugin

You almost certainly have the same URL configured manually already. Clients de-duplicate by URL and show only one entry. Remove the manual entry and reconnect.

A tool the assistant needs is missing

The approval was narrower than the task requires. Ask the assistant to call chatbase_whoami to see the permissions in use, then revoke the app under Connected apps and reconnect, approving the permissions it needs.

If a permission is missing from the consent screen entirely, your own role does not include it. An administrator has to grant it to you first.

A source is not live yet

Sources train as soon as they are written, but the work runs in the background. A new source reports untrained until it is live, then trained, or failed if it did not land. An edited one reports updated while it re-trains. Ask the assistant to re-read the source rather than assuming the write finished the job.

Responses do not stream

Streaming is not available over MCP. chatbase_chat always returns the complete response in one message.