> ## Documentation Index
> Fetch the complete documentation index at: https://cubed3-claude-gallant-ramanujan-o7e3ii.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP server
> Connect MCP-aware assistants to Cube through a hosted HTTPS endpoint with OAuth and admin-managed defaults.
Cube MCP (Model Context Protocol) lets MCP-compatible AI clients connect to Cube over HTTPS using OAuth.
The MCP server is available on [Premium and Enterprise plans](https://cube.dev/pricing).
Users need the [Viewer][ref-roles] role or higher to interact with the MCP server. Which tools a
user sees depends on their role — see [Available actions](#available-actions).
## What is MCP?
Model Context Protocol (MCP) is an open standard that enables AI assistants to securely connect to external data sources and tools. The Cube MCP server acts as a bridge between your AI assistant and Cube's analytics platform, allowing you to ask data questions directly from your coding environment.
## Overview
Cube hosts an MCP server endpoint for your tenant. MCP clients connect over HTTPS and authenticate via OAuth.
* **Endpoint:** `https:///api/mcp`
* **OAuth discovery:** `https:///.well-known/oauth`
* **OAuth flow:** Authorization Code + PKCE, `client_id` = `cube-mcp-client`, scope = `mcp-agent-access`
* **Deployment selection:** On connect, the client lands on the tenant **default deployment** set by your admin (or the first deployment you can access). Clients can also target a specific deployment and agent per request — see [Select a deployment and agent](#select-a-deployment-and-agent).
## Admin setup
### Prerequisites
Before enabling MCP, make sure you have:
* **Admin privileges** in your Cube instance
* An active Cube tenant
* MCP server URL configured
### 1) Confirm MCP server URL
MCP uses your Cube MCP server host. If the URL isn’t configured, the MCP page will show “MCP configuration is unavailable.”
### 2) Configure deployment access
Go to **Admin → MCP Server** and use the **Deployment Access** section to control which
deployments MCP clients can reach and where they connect by default:
* **Default deployment** — the deployment MCP clients connect to unless they explicitly
request another one. Choose **Automatic (first available)** to land each user on the
first deployment they can access.
* **Limit available deployments** — when off (the default), MCP clients can access **all**
deployments the user is permitted to see. Turn it on to restrict MCP to a chosen subset.
* **Available deployments** — when the limit is on, pick the deployments MCP clients may
access. Selecting none disables MCP access for the account.
Deployment access is always intersected with the user's
[role-based permissions][ref-roles] — clients can only reach deployments the
authenticated user is allowed to see.
## Connect to Claude
### Claude Code
```bash theme={null}
claude mcp add --transport http cube-mcp-server https:///api/mcp
```
#### Authentication and usage flow:
1. Run the command copied from **Admin → MCP Server → AI Clients → Claude Code**.
2. Then run Claude and use `/mcp` to list available servers.
3. Select `cube-mcp-server` and choose `Authenticate`.
4. A browser window opens for authentication.
5. Log into Cube and choose your tenant.
6. Return to Claude Code and start asking questions.
### Claude (Team/Enterprise)
1. Open Settings in Claude (web or desktop).
2. Scroll to **Integrations** and click **Add more**.
3. Use:
* **Integration name:** Cube MCP
* **Integration URL:** `https:///api/mcp`
4. Complete the OAuth flow to grant access.
5. Enable tools in any new chats.
#### Use Cube in Claude chat
1. Start a new chat in Claude.
2. Open the tools menu and enable **Cube MCP** (use the tools search if you have many tools).
3. Ask a data question. Toggle the tool off to disable it for that chat.
### Claude (Desktop app)
```json theme={null}
{
"mcpServers": {
"cube-mcp-server": {
"command": "npx",
"args": ["-y", "mcp-remote", "--transport", "http", "https:///api/mcp"]
}
}
}
```
## Connect to Cursor
Add the MCP endpoint under Tools & MCP Settings, then complete the OAuth flow.
```json theme={null}
{
"mcpServers": {
"cube-mcp-server": {
"command": "npx",
"args": ["-y", "mcp-remote", "--transport", "http", "https:///api/mcp"]
}
}
}
```
## Connect to Codex
Preferred (CLI):
```bash theme={null}
codex mcp add cube-mcp-server --url https:///api/mcp
```
If this is your first time using MCP in Codex, enable the feature in `~/.codex/config.toml`:
```editorconfig theme={null}
[features]
rmcp_client = true
```
Manual setup:
```editorconfig theme={null}
[features]
rmcp_client = true
[mcp_servers."cube-mcp-server"]
url = "https:///api/mcp"
```
Then run `codex mcp login cube-mcp-server` to authenticate.
## Connect to other MCP clients
For any MCP-compatible client:
1. Add a new server with the **MCP endpoint**.
2. The client will auto-discover OAuth and prompt for authentication.
3. Complete the OAuth flow to grant access to your Cube deployment.
## Select a deployment and agent
An MCP client is not locked to a single deployment for the whole session. After
connecting, it can discover the deployments and agents you can access and target a
specific one on each request.
Three tools work together:
* **`listDeployments`** — discovery. Returns every deployment you can access via MCP
(already filtered by the admin's deployment-access settings and your permissions) and
each deployment's agents. Use it to find valid `deploymentId` and `agentId` values
before calling `chat`. Every deployment offers an **Auto** agent (`agentId: null`) in
addition to any configured agents.
* **`chat`** — accepts two optional selection parameters:
* **`deploymentId`** — the deployment to use for this request. When omitted, the chat
uses the deployment from the current session (the default resolved at connect time).
* **`agentId`** — the agent to use for this request. When omitted or `null`, the
deployment's **Auto** agent is used. Pass a specific `agentId` to route to a
configured agent.
* **`loadQueryResults`** — paginates through the results of a previous query on the same
deployment context.
A typical client workflow:
Complete the OAuth flow. The session is scoped to the tenant default deployment (or
the first one you can access).
Call `listDeployments` to see the available `deploymentId` / `agentId` values.
Call `chat` with your `input`, optionally passing `deploymentId` and/or `agentId` to
target a specific deployment or agent. Omit both to use the session default deployment
with its Auto agent.
Requests are always validated against the admin's deployment-access settings. A deployment
that is outside the allow-list — or that you don't have permission to see — is rejected
with a **403 Forbidden** (`Deployment is not available via MCP for this account`), so
neither `listDeployments` nor the `chat` selection can reach an excluded deployment.
## Available actions
The MCP server exposes 16 tools, grouped below.
Every tool runs as the authenticated user. Queries respect the same
[permissions][ref-roles] as the rest of Cube, including row-level security — MCP is a new
way to reach your data, not a new access surface.
### Read and write tools
Each tool is annotated as read-only or destructive. MCP clients that honor these
annotations — including Claude — run read-only tools automatically and **always ask for
confirmation** before any of the four destructive ones: `updateDashboard`,
`publishDashboard`, `writeDataModelFile`, and `deleteDataModelFile`. Nothing that changes
a dashboard or your data model happens without an explicit approval.
### Deployments and chat
| Tool | Description |
| ------------------ | -------------------------------------------------------------------------------------- |
| `listDeployments` | Lists the deployments and agents you can reach over MCP. |
| `chat` | Asks a question of a Cube agent, optionally targeting a specific deployment and agent. |
| `loadQueryResults` | Paginates through the results of a previous query. |
See [Select a deployment and agent](#select-a-deployment-and-agent) for how these three
work together.
### Query and discovery
| Tool | Description | Access |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `searchDataModel` | Searches the semantic model by similarity — views and their measures and dimensions — to discover what is queryable. Returns compact records (name, title, description, type) to reference in `runQuery`. | Read-only |
| `runQuery` | Runs a Cube SQL query (PostgreSQL dialect) against the [SQL API][ref-sql-api]. Returns a schema, a page of rows, and `hasMore` / `totalRows` for pagination via `offset`. | Read-only |
Call `searchDataModel` before `runQuery` to find exact view and member names rather than
guessing them.
### Dashboard authoring
These tools build [workbooks][ref-workbooks] and [dashboards][ref-dashboards]
programmatically. Creating and editing workbooks requires the Explorer role or higher.
| Tool | Description | Access |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| `readWorkbook` | Reads a workbook — its name and its current dashboard draft and published configs. | Read-only |
| `createWorkbook` | Creates a new empty workbook, the container that holds reports and a dashboard. | Write |
| `createReport` | Saves a query plus its visualization as a report inside a workbook, and returns the `reportId` a chart widget references. | Write |
| `updateDashboard` | Saves the dashboard layout to the workbook **draft**. Replaces the full widget set and does not go live. | Destructive — prompts |
| `publishDashboard` | Publishes the current draft to make it live. Idempotent — republishing an unchanged draft is a no-op. | Destructive — prompts |
Drafts are the safety net here: `updateDashboard` only ever writes to the draft, so a
published dashboard keeps serving its previous version until you approve
`publishDashboard`. See [Build a dashboard](#build-a-dashboard) for the full sequence.
### Data model editing
These tools read and edit the semantic model **source** files. They are registered only
for users whose role grants permission to edit the semantic model — Admin and Developer by
default. Users without it never see them.
| Tool | Description | Access |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| `listDataModelFiles` | Lists the semantic model source files (raw YAML, JavaScript, or Python). | Read-only |
| `readDataModelFile` | Reads one file's raw source. | Read-only |
| `startDataModelEdit` | Enters [development mode][ref-dev-mode], starts a dev worker, and returns the dev `branchName` that every write tool requires. | Write |
| `writeDataModelFile` | Creates or overwrites a model source file on the dev branch (whole-file replacement). Recompiles the model and reports `valid` plus any `validationError`. | Destructive — prompts |
| `deleteDataModelFile` | Deletes a model source file on the dev branch. | Destructive — prompts |
| `getDataModelChanges` | Shows the diff of the dev branch against its parent — the pending changes, for review before committing. | Read-only |
#### How model edits stay safe
Letting an AI client edit your semantic model is safe because of four constraints built
into the MCP server:
* **Edits never touch production.** Every write goes to a personal dev branch named
`dev--`. The write tools reject any branch that isn't a dev branch, so
the deploy branch is never writable over MCP.
* **`startDataModelEdit` is the only entry point.** It returns the dev `branchName`, and
`writeDataModelFile` and `deleteDataModelFile` require it. There is no way to write
without going through it first.
* **Promotion is manual and human.** To publish model changes you commit the dev branch
from the Cube UI, as described in [Development mode][ref-dev-mode]. The MCP server
deliberately exposes no commit tool — an AI client can prepare changes, but only a
person can ship them.
* **Registration is permission-gated.** The six tools above are only offered to users
whose role allows editing the semantic model.
Review pending work with `getDataModelChanges` before you commit.
## Example workflows
### Ask a data question
Ask a question in natural language and let the agent do the planning: `chat` returns the
answer along with the SQL it generated, and `loadQueryResults` pages through large result
sets. Use this for summaries, trends, and ad-hoc analysis.
To drive the query yourself instead, call `searchDataModel` to find the right view and
members, then run your own SQL with `runQuery`.
### Build a dashboard
The five dashboard tools are designed to be used in order.
Call `createWorkbook` with a name. It returns the `workbookId` every later step needs.
If you were given an existing workbook to build into, call `readWorkbook` instead and
skip to the next step.
Call `createReport` once per chart, KPI tile, or table, passing the `workbookId` and
the SQL query that powers it. Each call returns a `reportId`.
Call `updateDashboard` with the complete widget set, referencing each `reportId` from
the previous step. This replaces the draft layout and saves to the workbook draft —
the live dashboard is unchanged. Your client will ask you to confirm.
Review the draft, then call `publishDashboard` to make it live. This also prompts for
confirmation. It returns the dashboard URL.
To change a dashboard later, call `readWorkbook` first and edit on top of the current
draft rather than overwriting it.
### Edit the data model
Call `startDataModelEdit` to enter development mode and get a dev `branchName`. Explore
the current source with `listDataModelFiles` and `readDataModelFile`, then apply changes
with `writeDataModelFile` or `deleteDataModelFile`, passing that `branchName`. Each write
recompiles the model and reports validation errors, so you can iterate until it compiles.
Review the result with `getDataModelChanges`, then commit the branch from the Cube UI to
publish it.
## Troubleshooting
* **MCP configuration is unavailable**: Configure the MCP server URL.
* **MCP OAuth integration is not configured**: Enable MCP in **Admin → Team & Security → OAuth Integrations**.
* **No deployments available / MCP access is disabled**: In **Admin → MCP Server → Deployment Access**, make sure **Limit available deployments** is off, or that at least one deployment is selected and the user has permission to access it.
* **`Deployment is not available via MCP for this account` (403)**: The requested deployment is excluded by the deployment-access allow-list or by the user's permissions. Call `listDeployments` to see which deployments are reachable, or adjust the allow-list in **Admin → MCP Server → Deployment Access**.
[ref-roles]: /admin/users-and-permissions/roles-and-permissions
[ref-sql-api]: /reference/core-data-apis/sql-api
[ref-workbooks]: /docs/explore-analyze/workbooks
[ref-dashboards]: /docs/explore-analyze/dashboards
[ref-dev-mode]: /docs/data-modeling/dev-mode