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.

Codex

Run this command in your terminal:

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.

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.

Claude Code

Run this command in your terminal:

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.

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.

Cursor

Add the following entry to .cursor/mcp.json in your project. Keep any servers already in the file.

{
  "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.

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:

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:

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:

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.