> ## 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 agents, manage the sources an 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.

<CardGroup cols={2}>
  <Card title="Endpoint" icon="link">
    `https://mcp.chatbase.co/api/mcp`
  </Card>

  <Card title="Authentication" icon="shield-check">
    OAuth 2.1, with no API key to create or paste
  </Card>
</CardGroup>

<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.
</Note>

## Claude and ChatGPT

Add Chatbase under **Settings → Connectors → Add custom connector**, using the endpoint above, then approve access when prompted.

<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 agent or a source, and editing a source. If ChatGPT says it cannot delete or edit something, raise the permission setting for the connector.
</Warning>

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

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http chatbase https://mcp.chatbase.co/api/mcp
    ```

    Then run `/mcp` and choose **Authenticate**.
  </Tab>

  <Tab title="Codex">
    ```bash theme={null}
    codex mcp add chatbase --url https://mcp.chatbase.co/api/mcp
    codex mcp login chatbase
    ```
  </Tab>

  <Tab title="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"
        }
      }
    }
    ```
  </Tab>

  <Tab title="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"
        }
      }
    }
    ```
  </Tab>
</Tabs>

## How sign-in works

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="The client receives a token">
    Access is granted to that one client, for that one workspace, limited to the permissions you approved.
  </Step>
</Steps>

<Info>
  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.
</Info>

### 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 you approve or deny the whole request.

| Resource      | Read                    | Write                    | Delete                    | Export            |
| ------------- | ----------------------- | ------------------------ | ------------------------- | ----------------- |
| 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 permissions are shown on the consent screen but are **not** selected by default. Approve them only if the app genuinely needs to remove data.

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 26 tools: `chatbase_whoami`, which every connected app can call to report its own access, plus 25 grouped by area.

<AccordionGroup>
  <Accordion title="Agents" icon="robot">
    List and inspect agents, create and clone them, update configuration, toggle auto-retrain, and send a chat message to an 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`
  </Accordion>

  <Accordion title="Sources" icon="database">
    Add, edit and remove the knowledge an 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`
  </Accordion>

  <Accordion title="Conversations" icon="messages">
    Export conversations for analysis, and update conversation metadata.

    `chatbase_export_conversations` · `chatbase_update_conversation`
  </Accordion>

  <Accordion title="Help desk" icon="ticket">
    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`
  </Accordion>
</AccordionGroup>

<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.
</Warning>

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

<Info>
  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.
</Info>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Responses do not stream">
    Streaming is not available over MCP. `chatbase_chat` always returns the complete response in one message.
  </Accordion>
</AccordionGroup>