> ## Documentation Index > Fetch the complete documentation index at: https://cubed3-claude-gallant-ramanujan-x9l6bc.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` * **Centralized endpoint:** `https:///mcp` — one fixed URL, on the Cube Cloud console domain rather than your tenant's own host, that proxies to the same server. Use it for MCP connector directories and clients that require one server URL registered up front, since the per-tenant endpoint above can vary by region or BYOC domain. * **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. Admin MCP Server page showing the Deployment Access section with the default deployment dropdown, the Limit available deployments switch, and the available deployments picker ## 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 20 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. | | `getDeploymentEnv` | Lists a deployment's environment variables, with secret-looking values redacted. Read-only — it cannot change them. | 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. ### Pre-aggregations | Tool | Description | Access | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | | `getPreAggregationStatus` | Lists the data model's pre-aggregations with their definitions and, for each, how many partitions exist, how many have been built, when the newest build landed, and the error if a build failed. | Read-only | | `buildPreAggregation` | Queues an on-demand build of one pre-aggregation and returns once it's accepted; poll `getPreAggregationStatus` for the result. Runs real queries against your data source, so it consumes warehouse resources. | Write | ### 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 | | `getBranchDiff` | Shows what any branch changed against an arbitrary base (the deploy branch by default) — the changed-file list with insertion/deletion counts plus the unified diff. Broader than `getDataModelChanges`, which only compares your own dev branch to its immediate parent. | 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