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

# MCP

> Connect an AI app to Chartbrew to read data, create datasets, and preview charts.

The Model Context Protocol (MCP) lets AI apps work with your Chartbrew data. You can find dashboards, read and refresh data, explore supported connections, create datasets, and create chart previews. Available actions depend on the permissions you approve.

## Before you connect

* Sign in to Chartbrew and open **Settings → MCP**.
* Copy the **Server URL**. Use this URL in your AI app. It can differ from the address you use to open Chartbrew.
* Use an AI app that supports remote MCP servers with Streamable HTTP.

Cloud clients, such as ChatGPT and Claude, need a public HTTPS URL. They cannot connect directly to `localhost`.

## Connect your AI app

The examples below use `https://api.example.com/mcp`. Replace it with the **Server URL** from Chartbrew. You can also copy the commands for your installation from **Settings → MCP**.

> [accordion] Codex
>
> Run this command in your terminal:
>
> ```bash theme={null}
> codex mcp add chartbrew --url 'https://api.example.com/mcp' --oauth-resource 'https://api.example.com/mcp' --oauth-client-registration dcr
> ```
>
> Sign in to Chartbrew when the browser opens and approve access. Start a new Codex task to use the connection.

> [accordion] ChatGPT
>
> 1. Enable **Developer mode** in **Settings → Security and login**, if your workspace allows it.
> 2. Open **Plugins**, select the plus button, and add Chartbrew with your server URL.
> 3. Connect, sign in to Chartbrew, and approve access.

> [accordion] Claude Code
>
> Run this command in your terminal:
>
> ```bash theme={null}
> claude mcp add --transport http --scope user chartbrew 'https://api.example.com/mcp'
> ```
>
> Open Claude Code, run `/mcp`, and select Chartbrew to sign in and approve access.

> [accordion] Claude
>
> 1. Open **Customize → Connectors** and add a custom connector. Your organization may require an owner to add it first.
> 2. Name it **Chartbrew** and enter your server URL.
> 3. Connect, sign in to Chartbrew, and approve access.

> [accordion] Cursor
>
> Add the following entry to `.cursor/mcp.json` in your project. Keep any servers already in the file.
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "chartbrew": {
>       "url": "https://api.example.com/mcp"
>     }
>   }
> }
> ```
>
> Open Cursor's MCP settings and connect Chartbrew. Sign in and approve access. If your client version does not support sign-in, use an [API key](#connect-with-an-api-key).

> [accordion] Other clients
>
> 1. Add a remote MCP server with your Chartbrew server URL.
> 2. Select **Streamable HTTP** as the transport and **OAuth** for authentication.
> 3. If the client asks for a registration method, select **dynamic registration (DCR)**.
> 4. Sign in to Chartbrew and approve access.

## Approve access

Check the app name and return address on the Chartbrew approval page. Select one team, review the requested permissions, and select **Allow access**. You can remove optional permissions before you continue.

| Permission | What the app can do |
| - | - |
| Read data | Find dashboards, charts, and datasets; read existing data; inspect supported connections and preview source data. |
| Refresh data | Fetch fresh data for existing datasets and charts. |
| Create chart previews | Create temporary charts for you to review in Chartbrew. |
| Create datasets | Save a validated source request as a dataset in a dashboard. |

Your Chartbrew role and dashboard access still apply. Source exploration and chart creation require a team owner or administrator. Other members can access only dashboards included when they approved access, and only while they retain access to them.

Each connection stays with the team you selected. Switching teams in Chartbrew does not change the connection. To use another team, connect again if your AI app supports multiple connections to the same server.

## Try the connection

Ask your AI app:

* "Find my website traffic dataset."
* "Show me recent changes to my dashboards."
* "Create a horizontal bar chart preview of the top 10 countries by visitors from my website traffic dataset."

Open a chart preview link to review the result in Chartbrew. Sign in if required. Select a dashboard to save the chart. Creating a preview alone does not add it to a dashboard.

Source exploration supports PostgreSQL, MySQL, and MCP connections. For other sources, create the dataset in Chartbrew first, then ask your AI app to read it. For MCP sources, approve the tools on the connection page before use.

## Connect with an API key

Use an API key if your client does not support OAuth sign-in.

1. Open **Team settings → API keys** in Chartbrew and create a key.
2. Select the permissions and project access you need. Chart preview and dataset creation permissions are off by default.
3. Copy the key and store it in your AI app's secret storage.
4. Add your Chartbrew server URL with **Streamable HTTP** transport.
5. Set this HTTP header in your client:

```text theme={null}
Authorization: Bearer <your API key>
```

Source exploration and chart creation require a key from a team owner or administrator with **All projects** access. Keys limited to selected projects can search and read data within those projects. Existing keys do not receive new permissions automatically.

## Remove access

For OAuth connections, open **Settings → MCP → Connected clients** and remove access for the app. The list includes your connections across teams. Removing one connection does not affect your teammates' connections or your other connections.

For API key connections, delete the key in **Team settings → API keys**.

## Self-hosted setup

Use a Chartbrew version that includes the MCP server. In the `server` directory, install dependencies and apply database migrations:

```bash theme={null}
npm ci
npm run db:migrate
```

Restart your API process. MCP runs in the existing API process. Apply the migrations even if you use only API keys.

The server URL defaults to `VITE_APP_API_HOST` plus `/mcp` in all environments. The existing client-host setting supplies the Chartbrew sign-in page URL. Use HTTPS outside local development.

If you need a separate MCP hostname, set:

```env theme={null}
CB_MCP_PUBLIC_URL=https://mcp.example.com/mcp
```

Route `/mcp`, `/oauth/*`, and `/.well-known/*` on that hostname to the same Chartbrew API process. Keep the normal API host available. Choose the public URL before users connect: changing it invalidates existing authorizations.

## Connection problems

* **The server cannot be reached:** Copy the URL from **Settings → MCP** again. Check that the AI app can reach it. Cloud clients need a public HTTPS endpoint.
* **Sign-in fails:** Check that the client supports OAuth with dynamic registration. For a separate MCP hostname, check the proxy routes listed above. Reconnect if the authorization has expired or was removed.
* **Data or actions are unavailable:** Check the selected team, your dashboard access, and the approved permissions. Connect again to approve additional permissions.
* **A source cannot be explored:** Use a supported source and check that you are a team owner or administrator. With an API key, also check **All projects** access. For MCP sources, approve the required tools in Chartbrew.


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