> ## Documentation Index
> Fetch the complete documentation index at: https://chatbase.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://modelcontextprotocol.io) 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

> [!NOTE]
>
> 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](https://claude.ai/directory/connectors/chatbase)**
>
> Works in Claude.ai and the Claude desktop app.

> **[Add to ChatGPT](https://chatgpt.com/plugins?q=chatbase)**
>
> 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.

> [!WARNING]
>
> 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**

```bash theme={null}
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:

```bash theme={null}
claude plugin marketplace add Chatbase-co/chatbase-plugin
claude plugin install chatbase@chatbase
```

**Codex**

```bash theme={null}
codex mcp add chatbase --url https://mcp.chatbase.co/api/mcp
codex mcp login chatbase
```

Or install the plugin:

```bash theme={null}
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`:

```json theme={null}
{
  "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:

```json theme={null}
{
  "mcpServers": {
    "chatbase": {
      "type": "http",
      "url": "https://mcp.chatbase.co/api/mcp"
    }
  }
}
```

> [!WARNING]
>
> 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.

> [!NOTE]
>
> 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`

> [!WARNING]
>
> 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.

<table>
  <thead>
    <tr>
      <th>Tool</th>
      <th>Permission</th>
      <th>Type</th>
      <th>Side effects</th>
    </tr>
  </thead>

  <tbody>
    <tr><td>`chatbase_whoami`</td><td>Always available</td><td>Read</td><td>—</td></tr>
    <tr><td>[`chatbase_list_agents`](https://chatbase.co/docs/api-v2/agents/list-agents)</td><td>`agents:read`</td><td>Read</td><td>—</td></tr>
    <tr><td>[`chatbase_create_agent`](https://chatbase.co/docs/api-v2/agents/create-agent)</td><td>`agents:write`</td><td>Write</td><td>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.</td></tr>
    <tr><td>[`chatbase_get_agent`](https://chatbase.co/docs/api-v2/agents/get-agent)</td><td>`agents:read`</td><td>Read</td><td>—</td></tr>
    <tr><td>[`chatbase_update_agent`](https://chatbase.co/docs/api-v2/agents/update-agent)</td><td>`agents:write`</td><td>Write</td><td>Changes the live AI agent's settings. A list field replaces the stored list.</td></tr>
    <tr><td>[`chatbase_delete_agent`](https://chatbase.co/docs/api-v2/agents/delete-agent)</td><td>`agents:delete`</td><td>Sensitive write</td><td>Deletes the AI agent and all its sources, and disconnects its integrations. Can't be undone.</td></tr>
    <tr><td>[`chatbase_update_agent_auto_retrain`](https://chatbase.co/docs/api-v2/agents/toggle-auto-retrain)</td><td>`sources:write`</td><td>Write</td><td>Turns retraining every 7 days on or off.</td></tr>
    <tr><td>[`chatbase_clone_agent`](https://chatbase.co/docs/api-v2/agents/clone-agent)</td><td>`agents:write`</td><td>Write</td><td>Creates a copy of the AI agent with its sources, except Notion sources. Counts toward your plan's AI agent limit.</td></tr>
    <tr><td>[`chatbase_chat`](https://chatbase.co/docs/api-v2/agents/chat-with-an-agent)</td><td>`chatlogs:write`</td><td>Write</td><td>Sends a message to the AI agent. Uses message credits, and the conversation appears in your logs.</td></tr>
    <tr><td>[`chatbase_export_conversations`](https://chatbase.co/docs/api-v2/conversations/export-conversations)</td><td>`chatlogs:export`</td><td>Read</td><td>—</td></tr>
    <tr><td>[`chatbase_search_conversations`](https://chatbase.co/docs/api-v2/conversations/search-conversations)</td><td>`chatlogs:export`</td><td>Read</td><td>—</td></tr>
    <tr><td>[`chatbase_update_conversation`](https://chatbase.co/docs/api-v2/conversations/update-conversation-status)</td><td>`chatlogs:write`</td><td>Sensitive write</td><td>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.</td></tr>
    <tr><td>[`chatbase_get_sources_summary`](https://chatbase.co/docs/api-v2/sources/get-sources-summary)</td><td>`sources:read`</td><td>Read</td><td>—</td></tr>
    <tr><td>[`chatbase_list_sources`](https://chatbase.co/docs/api-v2/sources/list-sources)</td><td>`sources:read`</td><td>Read</td><td>—</td></tr>
    <tr><td>[`chatbase_create_source`](https://chatbase.co/docs/api-v2/sources/create-source)</td><td>`sources:write`</td><td>Write</td><td>Adds a text, Q\&A or link source and starts training it.</td></tr>
    <tr><td>[`chatbase_get_source`](https://chatbase.co/docs/api-v2/sources/get-source)</td><td>`sources:read`</td><td>Read</td><td>—</td></tr>
    <tr><td>[`chatbase_delete_source`](https://chatbase.co/docs/api-v2/sources/delete-source)</td><td>`sources:delete`</td><td>Sensitive write</td><td>Removes the source's knowledge from the AI agent immediately. Can't be undone.</td></tr>
    <tr><td>[`chatbase_update_source`](https://chatbase.co/docs/api-v2/sources/update-source)</td><td>`sources:write`</td><td>Sensitive write</td><td>Overwrites the source and retrains it. The previous content is gone.</td></tr>
    <tr><td>[`chatbase_list_ticket_statuses`](https://chatbase.co/docs/api-v2/helpdesk/list-ticket-statuses)</td><td>`helpdesk_tickets:read`</td><td>Read</td><td>—</td></tr>
    <tr><td>[`chatbase_list_helpdesk_teams`](https://chatbase.co/docs/api-v2/helpdesk/list-teams)</td><td>`helpdesk_tickets:read`</td><td>Read</td><td>—</td></tr>
    <tr><td>[`chatbase_create_ticket`](https://chatbase.co/docs/api-v2/helpdesk/create-a-ticket)</td><td>`helpdesk_tickets:write`</td><td>Write</td><td>Creates a ticket for a customer. Your routing rules assign it unless you name an assignee.</td></tr>
    <tr><td>[`chatbase_list_tickets`](https://chatbase.co/docs/api-v2/helpdesk/list-tickets)</td><td>`helpdesk_tickets:read`</td><td>Read</td><td>—</td></tr>
    <tr><td>[`chatbase_search_tickets`](https://chatbase.co/docs/api-v2/helpdesk/search-tickets)</td><td>`helpdesk_tickets:read`</td><td>Read</td><td>—</td></tr>
    <tr><td>[`chatbase_get_ticket`](https://chatbase.co/docs/api-v2/helpdesk/get-a-ticket)</td><td>`helpdesk_tickets:read`</td><td>Read</td><td>—</td></tr>
    <tr><td>[`chatbase_update_ticket`](https://chatbase.co/docs/api-v2/helpdesk/update-a-ticket)</td><td>`helpdesk_tickets:write`</td><td>Sensitive write</td><td>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.</td></tr>
    <tr><td>[`chatbase_list_ticket_messages`](https://chatbase.co/docs/api-v2/helpdesk/list-ticket-messages)</td><td>`helpdesk_tickets:read`</td><td>Read</td><td>—</td></tr>
    <tr><td>[`chatbase_create_ticket_message`](https://chatbase.co/docs/api-v2/helpdesk/add-a-message-to-a-ticket)</td><td>`helpdesk_tickets:write`</td><td>Sensitive write</td><td>Sends a reply the customer receives. It can also change the ticket's status.</td></tr>
  </tbody>
</table>

### 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](https://chatbase.co/docs/api-v2/error-handling.md).

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.

> [!NOTE]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.