> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cube.dev/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.

[Using Cube with Claude](https://www.youtube-nocookie.com/embed/dQQsAA7Chvg)

This page covers the **Cube connector**, which gives an AI assistant direct access to Cube
through MCP. It is not [Cube agent skills](https://docs.cube.dev/docs/integrations/agent-skills.md) — workflows
for coding agents, which the Cube plugin for Claude Code bundles together with this
server — or [Agent Skills in Cube](https://docs.cube.dev/docs/explore-analyze/skills.md), which are saved
workflows your data team authors for Analytics Chat.

> [!NOTE]
>
> The MCP server is available on [all 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) — and on
> the tools an admin has [disabled](#3-disable-tools).

## 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. MCP clients connect over HTTPS and authenticate via OAuth.

* **Endpoint:** `https://cubecloud.dev/mcp`
* **OAuth flow:** Authorization Code + PKCE, scope = `mcp-agent-access`. Most clients discover OAuth automatically and use the public client ID `cube-mcp-client`. Microsoft 365 Copilot requires a separate [OAuth setup](#connect-to-microsoft-365-copilot). Backend apps can [authenticate with an API key](#authenticate-with-an-api-key) instead.
* **Account selection:** You sign in to Cube as part of the OAuth flow and, if you belong to more than one account, choose which one to connect.
* **Sessions:** The server opens a session on `initialize` and returns an `mcp-session-id` header. Send it on every later request — see [Call the MCP server](#call-the-mcp-server).
* **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). One connection reaches only the deployments its endpoint serves — see [Deployments in more than one region](#deployments-in-more-than-one-region).

### One endpoint for everyone

`https://cubecloud.dev/mcp` is the same URL for every account and region. Cube identifies
your account from the OAuth token and routes the connection to the endpoint that serves the
deployment you land on, so there is no per-tenant host to look up before you can connect.

> [!NOTE]
>
> If Cube runs in your own cloud account or on your own domain, use that console domain
> instead — `https://<your-console-domain>/mcp`.

Each deployment also keeps a **region-specific endpoint**, shown under
**Admin → MCP Server**. Prefer the single endpoint above unless you need a client to reach
a deployment's region directly without passing through the control plane, or you need a
deployment the single endpoint doesn't serve — see
[Deployments in more than one region](#deployments-in-more-than-one-region).

### Deployments in more than one region

Each MCP endpoint serves a set of deployments. Some regions serve their deployments from an
endpoint of their own; the others share one. A connection reaches only the deployments its
endpoint serves, and the single endpoint serves the same set as the endpoint of the
deployment you land on. If all your deployments share one endpoint, one connection reaches
them all, whatever their region.

When your deployments are served by more than one endpoint, **Admin → MCP Server** lists
every endpoint with the deployments it serves. Add one connector per endpoint through your
client's custom setup ([Claude](#claude-custom-connector), [ChatGPT](#chatgpt-custom-app),
[Codex](#codex-custom-connector), [Cursor](#connect-to-cursor),
[Microsoft 365 Copilot](#connect-to-microsoft-365-copilot),
[other clients](#connect-to-other-mcp-clients)); the Cube directory connector and plugins
use the single endpoint only. For Copilot, each endpoint needs its own OAuth client
registration. Give each connector its own name, such as **Cube** and **Cube EU**. The setup
steps on this page name it **Cube** (or `cube-mcp-server` in the Cursor and CLI examples), so
pick another name for the second one.

Signing in on an endpoint opens your default deployment if that endpoint serves it, and
otherwise the first deployment it serves that you can access. A deployment another endpoint
serves can't be used from that connection — 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, or a [custom role][ref-custom-roles] with the
  **Manage MCP server and connectors** permission
* An active Cube tenant

### 1) Check the MCP page

Go to **Admin → MCP Server**. The page shows the endpoint to hand to clients along with
ready-made setup snippets for each supported client. If it reads “MCP configuration is
unavailable,” the MCP server host isn’t configured for the account yet.

If your deployments are served by more than one endpoint, the page also lists each
endpoint with the deployments it serves. Add one connector per endpoint — see
[Deployments in more than one region](#deployments-in-more-than-one-region).

### 2) Configure deployment access

This step requires admin privileges; the section is hidden from other users.

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.

> [!NOTE]
>
> 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](https://mintcdn.com/cubed3/6RQxg3x5UdCrYZTh/images/docs/integrations/mcp-deployment-access.png?fit=max\&auto=format\&n=6RQxg3x5UdCrYZTh\&q=85\&s=6cc2db0008d965dfa61cc6701598f20d)

### 3) Disable tools

This step requires admin privileges; the section is hidden from other users.

Go to **Admin → MCP Server**, select tools in the **Disabled tools** section, and click
**Save**. Disabled tools are hidden from every MCP client and refuse calls, for every user.
This applies to interactive sign-in from clients like Claude, ChatGPT, and Cursor, and to
[tokens issued for an API key](#authenticate-with-an-api-key). To turn a tool back on,
deselect it and click **Save**.

A change reaches each client with its next access token, within 24 hours. Until then, a
client that is already connected can still list and call a tool you've disabled.

The picker lists every tool the MCP server can offer, by the names in [Available
actions](#available-actions). It also lists tools that only back the interactive views some
clients render, such as `loadDashboardTiles` and `openExploration`. Disabling one of them
breaks the views that call it.

> [!WARNING]
>
> **Disabling a tool doesn't limit the agent behind `chat`.** The agent uses its own tools,
> not the MCP ones. For example, with `runQuery` disabled, the agent can still query your
> data through [`chat`](#deployments-and-chat). To block that too, disable `chat`.

## Connect to Claude

Cube is available in the
[Claude Connectors Directory](https://claude.ai/customize/connectors). Connect it once
and use it in Claude on the web, desktop, or Claude Code. The listing uses the
[single endpoint](#one-endpoint-for-everyone), so there is no endpoint to paste or local
server to configure.

1. In Claude on the web or desktop, open **Customize → Connectors**.
2. Click **+**, choose **Browse connectors**, and search for **Cube**.
3. Select Cube and click **Connect**.
4. Complete the Cube OAuth flow and choose your account.

On a Team or Enterprise plan, an owner may need to enable Cube first under
**Admin settings → Connectors**.

To use Cube in a chat, open the tools menu and enable the Cube connector, then ask a data
question. In Claude Code, run `/mcp` to confirm the connector is available and authenticate
if prompted. Alternatively, install the [Cube plugin](https://docs.cube.dev/docs/integrations/agent-skills.md#claude-code),
which bundles this server with Cube agent skills.

![](https://lgo0ecceic.ucarecd.net/68c3e7e2-def2-4aec-84a5-8cded3473def/)

### Custom connector

To connect Claude to a [region-specific endpoint](#one-endpoint-for-everyone) or your own
console domain, add Cube as a custom connector. Copy the endpoint from **Admin → MCP Server**.

1. In **Customize → Connectors**, click **+** and choose **Add custom connector**.
2. Name it **Cube** and enter the endpoint as the URL.
3. Click **Add**, then **Connect**, and complete the Cube sign-in.

On a Team or Enterprise plan, only an owner can add a custom connector, under
**Admin settings → Connectors**. Members can then connect to it.

In Claude Code, add the endpoint with the CLI, then run `/mcp` to authenticate:

```bash theme={"dark"}
claude mcp add --transport http cube-mcp-server <mcp-endpoint>
```

## Connect to ChatGPT

Install the Cube plugin to connect ChatGPT to Cube. The plugin uses the
[single endpoint](#one-endpoint-for-everyone).

1. In ChatGPT, open **Customize → Plugins**.
2. In **Search plugins**, enter **Cube**. More than one plugin is named Cube: pick the one
   described as **Query governed business data**.
3. Click **+** to install it, then complete the Cube OAuth flow and choose your account.

On a Business or Enterprise plan, a workspace admin may need to enable the Cube plugin first.

### Custom app

To connect ChatGPT to a [region-specific endpoint](#one-endpoint-for-everyone) or your own
console domain, create a custom app in Developer mode. Copy the endpoint from **Admin → MCP Server**.

1. In **Settings → Apps → Advanced settings**, turn on **Developer mode**.
2. Click **Create app**, name it **Cube**, and enter the endpoint as the MCP
   server URL.
3. Choose **OAuth** for authentication, create the app, and complete the Cube sign-in.

On a Business or Enterprise plan, a workspace admin may need to enable Developer mode or
create the app for the workspace.

## Connect to Microsoft 365 Copilot

> [!WARNING]
>
> Microsoft 365 Copilot setup is currently in preview. Reach out to the
> [Cube support team](https://docs.cube.dev/admin/account-billing/support.md) to activate it for your account.

An admin can get the OAuth client details for the selected MCP endpoint from
**Admin → MCP Server → Microsoft 365 Copilot setup**.

1. On the MCP Server page, select the [single endpoint or a region-specific
   endpoint](#one-endpoint-for-everyone), then click **Get OAuth client details**.
   The credentials and OAuth URLs correspond to the displayed **MCP endpoint**.
2. In the [Teams developer portal](https://dev.teams.microsoft.com/), open
   **Tools → OAuth client registration** and create a registration with these values:

   | Cube Admin | Teams OAuth client registration |
   | - | - |
   | Client ID, Client secret, Scope | Same-named fields |
   | Authorization URL | Authorization endpoint |
   | Token URL | Token endpoint and Refresh endpoint |
   | MCP endpoint | Base URL |

   Set **Restrict usage by app** to **Any Teams app** and leave PKCE enabled.
   [Microsoft warns](https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/plugin-authentication-oauth#use-the-teams-developer-portal)
   that binding an MCP registration to an existing Teams app ID causes Copilot tool calls
   to return `404`.

   For **Restrict usage by org**, choose **My organization only** for one Microsoft 365
   organization or **Any Microsoft 365 organization** for cross-organization use.
3. Save the registration. In your Microsoft 365 Copilot plugin manifest, set the MCP
   server `url` to the **MCP endpoint** you entered as **Base URL**, use `OAuthPluginVault`
   as the runtime authentication type, and set `reference_id` to the OAuth client
   registration ID from the portal.
   Follow [Microsoft's OAuth setup
   guide](https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/plugin-authentication-oauth)
   for the remaining plugin configuration.

Cube registers the Teams redirect URI
`https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect` for this client. The client
secret is shared by every Cube account and cannot be rotated per account. Access is still
granted per user: each user signs in to Cube to authorize Copilot.

## Connect to Cursor

Add the MCP endpoint under Tools & MCP Settings, then complete the OAuth flow. For a
[region-specific endpoint](#one-endpoint-for-everyone), replace the URL with the one from
**Admin → MCP Server**.

```json theme={"dark"}
{
  "mcpServers": {
    "cube-mcp-server": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "--transport", "http", "https://cubecloud.dev/mcp"]
    }
  }
}
```

## Connect to Codex

Install the Cube plugin to connect Codex to Cube. The plugin uses the
[single endpoint](#one-endpoint-for-everyone).

1. In Codex, open **Customize → Plugins**.
2. In **Search plugins**, enter **Cube**. More than one plugin is named Cube: pick the one
   described as **Query governed business data**.
3. Click **+** to install it, then complete the Cube OAuth flow and choose your account.

### Custom connector

To connect Codex to a [region-specific endpoint](#one-endpoint-for-everyone) or your own
console domain, add the endpoint as an MCP server. Copy the endpoint from
**Admin → MCP Server**. The IDE extension and the CLI share this configuration.

With the CLI:

```bash theme={"dark"}
codex mcp add cube-mcp-server --url <mcp-endpoint>
```

If this is your first time using MCP in Codex, enable the feature in `~/.codex/config.toml`:

```editorconfig theme={"dark"}
[features]
rmcp_client = true
```

To set it up manually instead, add this to `~/.codex/config.toml`:

```editorconfig theme={"dark"}
[features]
rmcp_client = true

[mcp_servers."cube-mcp-server"]
url = "<mcp-endpoint>"
```

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.

## Authenticate without a browser

A backend app can get an MCP access token with a Cube [API key][ref-api-keys] instead of
an interactive sign-in. Both the [single endpoint and region-specific
endpoints](#one-endpoint-for-everyone) support this flow. Prefer the single endpoint, and
use a region-specific one for a deployment the single endpoint doesn't serve — see
[Deployments in more than one region](#deployments-in-more-than-one-region):

| | Single endpoint | Region-specific endpoint |
| - | - | - |
| MCP endpoint | `https://cubecloud.dev/mcp` | `https://<host>/api/mcp` |
| Token endpoint | `https://cubecloud.dev/mcp/oauth/token` | `https://<host>/oauth/token` |
| Discovery | `https://cubecloud.dev/.well-known/oauth-authorization-server` | `https://<host>/.well-known/oauth-authorization-server` |

For your own console domain, replace `https://cubecloud.dev` with that domain. For a
region-specific endpoint, copy the host from **Admin → MCP Server**. Request a token
from the matching token endpoint and set `resource` to the MCP endpoint you will call.
Client authentication is `client_id=cube-api-key` and `client_secret=<Cube API key>`,
sent as HTTP Basic or as form fields.

API keys must be enabled for your account, and the key must not be limited to particular
deployments or to [specific endpoints](https://docs.cube.dev/admin/account-billing/api-keys.md#endpoint-scope). Tokens last up to one hour, or less if the key expires sooner.
There is no refresh token: request a new one when it expires.

### Act as the key's owner

The `client_credentials` grant returns a token that acts as the API key's owner. A
typical setup is a dedicated service user that holds one role, with its own key.

```bash theme={"dark"}
export MCP_URL="https://cubecloud.dev/mcp"
export TOKEN_URL="https://cubecloud.dev/mcp/oauth/token"

curl -s "$TOKEN_URL" \
  -d grant_type=client_credentials \
  --data-urlencode "resource=$MCP_URL" \
  -d client_id=cube-api-key \
  --data-urlencode "client_secret=$CUBE_API_KEY"
```

```json theme={"dark"}
{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "mcp-agent-access"
}
```

### Act as another user

The `urn:ietf:params:oauth:grant-type:token-exchange` grant ([RFC
8693](https://www.rfc-editor.org/rfc/rfc8693)) lets one admin key act as any existing
Cube user, admins included. The token carries that user's permissions and data access.
It requires an admin's API key.

```bash theme={"dark"}
curl -s "$TOKEN_URL" \
  -u "cube-api-key:$CUBE_API_KEY" \
  -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
  --data-urlencode "resource=$MCP_URL" \
  --data-urlencode "subject_token=user@example.com" \
  -d subject_token_type=urn:cube:params:oauth:token-type:email
```

The response also includes
`"issued_token_type": "urn:ietf:params:oauth:token-type:access_token"`. Deactivated users
and unknown emails are refused. If your account has the [Audit Log][ref-audit-log]
enabled, every token issued this way is recorded there.

### Limit a token to specific tools

Add `tool:<name>` entries to `scope` to limit the token to those tools — others are
neither listed nor callable. Names aren't validated, so a misspelled tool is simply
unavailable. `mcp-agent-access` is optional here and doesn't widen the limit. This works
with either grant:

```bash theme={"dark"}
curl -s "$TOKEN_URL" \
  -u "cube-api-key:$CUBE_API_KEY" \
  -d grant_type=client_credentials \
  --data-urlencode "resource=$MCP_URL" \
  --data-urlencode "scope=mcp-agent-access tool:runQuery tool:searchDataModel"
```

A tool-limited token is accepted only by the MCP endpoints, not by Cube's other APIs.
Tools an admin has [disabled](#3-disable-tools) stay unavailable, even if the scope names them.
Note that `tool:chat` gives access to the whole agent, including the write-capable tools it uses — see
[Deployments and chat](#deployments-and-chat).

### Call the MCP server

Send the token as `Authorization: Bearer <token>` to `$MCP_URL`. The example below
negotiates protocol version `2025-11-25`. Start with `initialize`, then send the
`mcp-session-id` header it returns on every later request. For a region-specific endpoint,
set `MCP_URL` and `TOKEN_URL` to the matching URLs in the table above.

```bash theme={"dark"}
TOKEN=$(curl -s "$TOKEN_URL" \
  -u "cube-api-key:$CUBE_API_KEY" \
  -d grant_type=client_credentials \
  --data-urlencode "resource=$MCP_URL" | jq -r .access_token)

SESSION_ID=$(curl -s -D - -o /dev/null "$MCP_URL" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"my-backend","version":"1.0.0"}}}' \
  | awk 'tolower($1) == "mcp-session-id:" { print $2 }' | tr -d '\r')

curl -s "$MCP_URL" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
```

With the [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk),
pass the token to the Streamable HTTP transport, which handles the session for you:

```typescript theme={"dark"}
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const mcpUrl = "https://cubecloud.dev/mcp";
const tokenUrl = "https://cubecloud.dev/mcp/oauth/token";

const tokenResponse = await fetch(tokenUrl, {
  method: "POST",
  body: new URLSearchParams({
    grant_type: "client_credentials",
    resource: mcpUrl,
    client_id: "cube-api-key",
    client_secret: process.env.CUBE_API_KEY!,
  }),
});
if (!tokenResponse.ok) {
  throw new Error(`Token request failed: ${await tokenResponse.text()}`);
}
const { access_token } = await tokenResponse.json();

const transport = new StreamableHTTPClientTransport(new URL(mcpUrl), {
  requestInit: { headers: { Authorization: `Bearer ${access_token}` } },
});
const client = new Client({ name: "my-backend", version: "1.0.0" });
await client.connect(transport);

const { tools } = await client.listTools();
console.log(tools.map((tool) => tool.name));
```

### Errors

| `error` | Status | Cause |
| - | - | - |
| `invalid_client` | 401 | `client_id` isn't `cube-api-key`, or the secret isn't a valid Cube API key. |
| `invalid_request` | 400 | `subject_token` is missing or unknown, or `subject_token_type` is wrong. |
| `invalid_scope` | 400 | `scope` was sent more than once. |
| `access_denied` | 403 | The request isn't allowed — for example, a non-admin key naming a user, a key limited to particular deployments or to specific endpoints, or a deactivated user. |
| `invalid_target` | 400 | `resource` isn't a Cube MCP endpoint, or no deployment you can reach is served by it. |

## 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, among the deployments the connection's endpoint serves — see
[Deployments in more than one region](#deployments-in-more-than-one-region).

[MCP Multi Agent Support](https://www.youtube-nocookie.com/embed/LBELbitqBAc)

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`. A deployment offers an **Auto** agent (`agentId: null`) in
  addition to any configured agents, unless an admin has turned Auto off for it.
* **`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, the session's
    agent is used (see [Pin an agent for the session](#pin-an-agent-for-the-session)).
    Pass `null` for **Auto**, or 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:

**1. Connect**

Complete the OAuth flow. The session is scoped to the tenant default deployment (or
the first one you can access); on another endpoint, see
[Deployments in more than one region](#deployments-in-more-than-one-region).

**2. Discover**

Call `listDeployments` to see the `deploymentId` / `agentId` values you can target. It
also lists deployments behind other endpoints, each with the endpoint that serves it.

**3. Chat**

Call `chat` with your `input`, optionally passing `deploymentId` and/or `agentId` to
target a specific deployment or agent. Omit both to use the session's deployment
and 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 <id> is not available via MCP for this account`), so
neither `listDeployments` nor the `chat` selection can reach an excluded deployment.

A deployment that another endpoint serves can't be used from this connection.
`listDeployments` names the endpoint to connect to beside it, and a request that names the
deployment returns an error naming that endpoint instead of running. Add a connector for
that endpoint to use it.

### Pin an agent for the session

To run every request of a session on one agent, connect with its `agentId`:

```text theme={"dark"}
https://cubecloud.dev/mcp?agentId=<agentId>
```

A client that can't set a query parameter can send the same value as an
`x-mcp-agent-id` header instead (checked first; `mcp-agent-id` is a lower-priority
alias). A per-call `agentId` on `chat` still overrides it for that one request. The pinned
id isn't checked at connect time: an id that doesn't exist on the deployment, or that you
can't use, makes each `chat` call fail rather than fall back to another agent. An agent
belongs to one deployment, so a `chat` call whose `deploymentId` targets another deployment
ignores the pin and uses that deployment's default agent (or Auto) unless it passes its own
`agentId`.

When the client names no agent, the session uses the deployment's
[default agent](https://docs.cube.dev/admin/ai/multi-agent.md#default-agent-and-auto) (or Auto). With Auto turned
off, `agentId: null` runs on the default agent too.

## Target a dev-mode branch

By default, an MCP session reads and queries the deployed data model. To exercise a
[development mode][ref-dev-mode] branch — a data-model change plus its agent
configuration (skills, rules, spaces) — before it's committed, connect with the dev
`branchName` returned by `startDataModelEdit`:

```text theme={"dark"}
https://cubecloud.dev/mcp?branchName=dev-<user>-<hash>
```

A client that can't set a query parameter on the endpoint can send the same value as an
`x-mcp-branch-name` header instead (checked first; `mcp-branch-name` is a second, lower-priority
alias). Only an active dev branch is accepted — `main`, the deploy branch, or a branch
with no dev worker running is rejected at connect time with a `400` error, never a silent
fallback to the deployed model.

Once connected this way, every branch-aware tool below defaults to that branch instead of
the deployed model — you don't need to keep passing `branchName` on each call. Any tool
can still override it per call: pass a different `branchName` to target another branch for
just that one request, or pass `null` to force the deployed model for one call on an
otherwise branch-scoped session. Every response echoes back the branch it actually ran on
as `branchName` (`null` means the deployed model), so a client can always confirm what it
queried.

## Available actions

The MCP server exposes the tools below, grouped by purpose.

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 — with one exception, reachable two
ways: deleting a [workspace folder][ref-folders] skips the content-permission check the
Workspace page applies, whether it's [`deleteFolder`](#dashboard-authoring) or the
agent behind [`chat`](#deployments-and-chat) doing the deleting.

### Read and write tools

Each tool is annotated as read-only, write, or destructive. MCP clients that honor these
annotations — including Claude — run read-only tools automatically and **always ask for
confirmation** before any destructive one. The destructive tools on this page are
`updateReport`, `deleteReport`, `moveWorkspaceItem`, `renameFolder`, `deleteFolder`,
`updateDashboard`, `publishDashboard`, `writeDataModelFile`, `deleteDataModelFile`,
`mergeToDefaultBranch`, and `discardDataModelChanges`. A tool annotated write, not
destructive, may run without a prompt — including
`commitDataModelChanges`, which can publish straight to production in one case; see [How
model edits stay safe](#how-model-edits-stay-safe). A tool annotated read-only can still
cause a write once it runs — `chat` is that case; see [Deployments and
chat](#deployments-and-chat).

### Deployments and chat

| Tool | Description | Access |
| - | - | - |
| `listDeployments` | Lists the deployments and agents you can access over MCP, and names the endpoint for each deployment this connection can't use. | Read-only |
| `chat` | Asks a question of a Cube agent, optionally targeting a specific deployment and agent. Pass `branchName` to have the agent answer from a dev branch's model instead of the deployed one. | Read-only — see warning below |
| `loadQueryResults` | Paginates through the results of a previous query. | Read-only |

See [Select a deployment and agent](#select-a-deployment-and-agent) for how these three
work together.

> [!WARNING]
>
> `chat`'s **Read-only** annotation covers only the MCP call itself, not what the agent
> does in response. It's the same agent Analytics Chat uses, with the same write-capable
> tools — creating reports, organizing workspace folders — when the caller's access allows
> it, and the agent's own folder actions run with no confirmation step — unlike
> `moveWorkspaceItem`, `renameFolder`, and `deleteFolder` below, which a client prompts
> for. A client that runs `chat` automatically because the annotation says read-only can
> still cause an unconfirmed write through the agent's own reply.

A chat conversation is pinned to whichever branch answered its first message — later
messages in the same conversation stay on that branch, and `loadQueryResults` pages using
it. Passing a different `branchName` while resuming an existing `chatId` fails rather than
silently switching branches mid-conversation: omit `branchName` to keep talking on the
conversation's branch, or omit `chatId` to start a new conversation on the one you want.

### 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`. Pass the dev `branchName` from `startDataModelEdit` to search that branch's model, including members that don't exist in production yet. | 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`. Pass the dev `branchName` from `startDataModelEdit` to query that branch instead of the deployed model. Pass a `securityContext` object to run this one query under [another security context][ref-agent-security-context]; the result echoes it. Pass `periodComparisons` to add [period comparison columns](#period-comparisons). | Read-only |

Call `searchDataModel` before `runQuery` to find exact view and member names rather than
guessing them — pass the same `branchName` to both so the members you find are the ones the
query will see.

Omitting `branchName` on a call uses the session's branch if you [connected with
one](#target-a-dev-mode-branch), or the deployed model otherwise; passing `null` forces the
deployed model for that one call regardless of the session. Passing a `branchName` that
isn't an active dev branch — for example the deploy branch's own name, or a feature branch
with no dev worker running — fails with an error rather than silently answering from the
deployed model, so a query aimed at the wrong branch never looks like a query that just
returned no rows.

#### Period comparisons

Pass `periodComparisons` to `runQuery` to compare measures with an earlier period, such as
month over month or year over year, instead of writing `LAG()` or a self-join. Cube runs the
same query over the shifted period and adds the derived columns to `schema` and `data`, next to
each measure. The values, titles, and formats are the same as in a workbook report with a
[period comparison][ref-period-comparison].

Each entry takes:

* `measure` — the measure to compare. Pass its member name, e.g., `revenue` for
  `MEASURE(revenue)`, or its alias in the query.
* `timeDimension` — the time dimension to shift, by member name or alias. Select it in the
  query at the `day`, `week`, `month`, `quarter`, or `year` granularity, or filter on it with
  a date range.
* `offset` — how far back the earlier period is, e.g., `{ "amount": 1, "unit": "month" }`.
  `unit` is one of `day`, `week`, `month`, `quarter`, or `year`.
* `outputs` — the columns to add: `previous` (the value in the earlier period), `difference`,
  and `percentChange` (a ratio, e.g., `0.25` for +25%). Defaults to `["previous"]`.

```json theme={"dark"}
{
  "sqlQuery": "SELECT DATE_TRUNC('month', created_at) AS month, MEASURE(revenue) AS total_revenue FROM orders_view GROUP BY 1",
  "periodComparisons": [
    {
      "measure": "revenue",
      "timeDimension": "created_at",
      "offset": { "amount": 1, "unit": "year" },
      "outputs": ["previous", "percentChange"]
    }
  ]
}
```

The result lists the added columns in `periodComparisonColumns`, each with its `name`, `title`,
`measure`, `timeDimension`, `offset`, and `output`. Column names follow the
`<column>__pop_<amount><unit>_<output>` pattern, where `<column>` is the measure's column in
the result, e.g., `total_revenue__pop_1year_previous`.

Cube computes the comparison before it slices the page, so a row is compared correctly even
when its earlier period is on another page. If the earlier period has no rows, an additive
measure such as a sum or a count reads `0`, and other measures read `null`.

If a comparison can't be computed, `runQuery` still returns the rows, without that comparison's
columns, and explains why in `periodComparisonErrors`.

### 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. Pass `workbookId` to create a report inside a workbook and get the `reportId` a chart widget references; omit `workbookId` to save a standalone [exploration](https://docs.cube.dev/docs/explore-analyze/explore.md#saving-explorations) instead. Pass `folderId` to file a standalone exploration in a [workspace folder][ref-folders]. | Write |
| `readReport` | Reads one workbook report or standalone exploration by id — its title, SQL, chart spec, placement, and a shareable URL. | Read-only |
| `updateReport` | Edits an existing workbook report or exploration in place, keeping its `reportId`. Send only the fields you want to change — including `folderId` to move a standalone exploration into a [workspace folder][ref-folders]. | Destructive — prompts |
| `deleteReport` | Deletes a workbook report or exploration. | Destructive — prompts |
| `listWorkspaceItems` | Lists the [workspace folders][ref-folders], workbooks, and standalone explorations, each with its `type`, `id`, `name`, and the `folderId` it's filed in. Lists one folder level, or pass `search` to match names across every folder. Pass `url` with a dashboard or workbook link the user pasted to get that one workbook and its `workbookId`. | Read-only |
| `moveWorkspaceItem` | Moves a folder, workbook, or standalone exploration into another folder, or to the workspace root. A folder moves with everything inside it. | Destructive — prompts |
| `createFolder` | Creates an empty workspace folder, at the root or inside another folder. | Write |
| `renameFolder` | Renames a workspace folder. | Destructive — prompts |
| `deleteFolder` | Deletes a workspace folder. The items inside it move to the workspace root. A folder that holds subfolders can't be deleted. | Destructive — prompts |
| `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.

Call `listWorkspaceItems` to get the ids the other tools take: a folder's id is the
`folderId` on `createReport`, `updateReport`, and `moveWorkspaceItem`, a workbook's id is the
`workbookId` on `readWorkbook` and `updateDashboard`, and a standalone exploration's id is
the `reportId` on `readReport` and `updateReport`. `deleteFolder` [destroys less than the
Workspace page but checks less too][ref-deleting-folders].

When the user pastes a link to a dashboard, an embedded dashboard, or a workbook, call
`listWorkspaceItems` with the link as `url`. It returns the workbook as one `WORKBOOK` item,
and its `id` is the `workbookId`. If the link points to another deployment, the call fails
with an error that names that deployment's `deploymentId`. Call `listWorkspaceItems` again
with the link and that `deploymentId`, and pass the same `deploymentId` to the workbook
tools that follow, such as `readWorkbook` and `updateDashboard`. Every tool in this section
takes an optional `deploymentId`, and without it the tool uses the session's deployment.
If the link points to nothing the user can open, the call fails.

**To change an existing report, use `updateReport` — never recreate it.** A dashboard's
chart widget points at a specific `reportId`, so replacing a report with a new one orphans
every widget referencing it. The same caution applies to moving a report between workbooks:
a widget resolves its report from its *own* workbook's report list, so changing a report's
`workbookId` empties the tiles on the old workbook's dashboard. Call `readWorkbook` and
re-point those widgets with `updateDashboard` first.

### 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). Pass `branchName` to list a dev branch's files instead of the deploy branch's. | Read-only |
| `readDataModelFile` | Reads one file's raw source. Pass `branchName` to read it from a dev branch instead of the deploy branch. | 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 pending changes on the dev branch against its parent, for review before committing: the changed-file list with per-file line counts, the unified diff, and a link that opens the changes in the [Data model IDE][ref-reviewing-changes]. | Read-only |
| `getBranchDiff` | Shows what **any** branch changed against the deploy branch: the changed-file list with per-file line counts, plus the unified diff. | Read-only |
| `getDeploymentEnv` | Lists the deployment's environment variables, with every secret-looking value redacted to `[ENCRYPTED]`. Useful for confirming configuration is present and shaped as expected. | Read-only |

`getDataModelChanges` answers "what have I changed?" for your own dev branch against its
immediate parent. `getBranchDiff` answers "what did this branch change?" for any branch,
including feature branches — reach for it when a change edits existing cubes, where the
file list looks identical on both branches and `listDataModelFiles` reveals nothing.

> [!NOTE]
>
> `getDeploymentEnv` never returns secret values. Anything that looks like a credential is
> replaced with `[ENCRYPTED]` before it leaves Cube, so an AI client can verify that a
> variable is set without ever seeing what it is set to.

### How model edits stay safe

Model editing over MCP is constrained by several mechanisms — most enforced by the MCP
server, one by clients that honor tool annotations, and one that is yours to apply —
with one gap noted below:

* **File writes never touch production.** Every write goes to a personal dev branch named
  `dev-<user>-<hash>`. `writeDataModelFile` and `deleteDataModelFile` reject any branch
  that isn't a dev branch, so no file edit can land on the deploy branch directly.
* **`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.
* **Merging a branch to production prompts for confirmation.** `mergeToDefaultBranch` — the tool
  that publishes an already-committed branch — is marked destructive, so a client always
  prompts for confirmation. See [Committing and publishing
  changes](#committing-and-publishing-changes).
* **Registration is permission-gated.** Every tool in Data model editing, Committing and
  publishing changes, and Pre-aggregations — the six model-editing tools, `getBranchDiff`,
  `getDeploymentEnv`, the six commit and branch tools, and both pre-aggregation tools — is
  offered only to users whose role allows editing the semantic model. A Viewer never sees
  any of them.
* **Deploy-branch writes are permission-checked at call time.** A role scoped to **Edit data
  model on dev branches** still sees every tool listed above registered, but `mergeToDefaultBranch`
  and `commitDataModelChanges` with `confirmPublishToDefaultBranch` fail for that role, the
  same as any other write targeting the deploy branch.
* **Verify on the branch, before a merge, not after.** Pass the dev `branchName` to
  `runQuery` to check that an edit returns the right data — `valid: true` from
  `writeDataModelFile` only means the model compiles, not that it's correct.

> [!WARNING]
>
> `commitDataModelChanges` is a second route to production: a dev branch created from the
> deploy branch commits straight onto it, live, when the call sets
> `confirmPublishToDefaultBranch`. That tool is **not** annotated destructive, so a client
> isn't guaranteed to prompt first. For a role that holds full **Edit data model**, the
> tool's own description is the only thing standing in the way — it tells the agent to set
> the flag only on your explicit say-so, never to retry a refusal on its own.

### Committing and publishing changes

Editing the model with the tools above only ever writes to a personal dev branch's
working copy — reachable on that branch's endpoints, and in the Cube UI once you've
switched to it, but invisible to everyone else until it's committed. These tools commit
that work, publish it, or throw it away. They're registered under the same
semantic-model permission as the data model tools above, and a client can call them
without ever using the Cube UI.

| Tool | Description | Access |
| - | - | - |
| `getBranchState` | Reports the branch this session works on, the branch you're looking at in the Cube UI, the deploy branch, and whether the session's branch has uncommitted edits. | Read-only |
| `commitDataModelChanges` | Commits the dev branch's edits onto the branch it was created from — including the deploy branch, live, when the call sets `confirmPublishToDefaultBranch`. | Write — see [How model edits stay safe](#how-model-edits-stay-safe) |
| `commitToNewBranch` | Commits the dev branch's edits to a new branch instead, optionally opening a pull request. | Write |
| `mergeToDefaultBranch` | Merges a committed branch into the deploy branch, making it live for everyone. | Destructive — prompts |
| `discardDataModelChanges` | Resets the dev branch to its parent (or to a given commit hash), throwing away pending edits. | Destructive — prompts |
| `switchUserBranch` | Switches your own Cube UI over to a branch, the same action as its branch switcher, so you can see and test what was committed. | Write |

These mirror the **Commit**, **Merge into …** / **Publish to …**, and branch-switching
actions described in [Development mode][ref-dev-mode] — a client can now drive that same
flow instead of asking you to click through it. `mergeToDefaultBranch` matches
**Publish to …**: it always targets the deploy branch.

Call `getBranchState` before editing, to see whether the MCP session's branch and the
branch your Cube UI shows are the same, and again after committing, to see whether you
still need `switchUserBranch` to see the result.

### Pre-aggregations

These tools inspect and trigger [pre-aggregation][ref-pre-aggregations] builds. They are
registered under the same semantic-model permission as the data model tools above.
`buildPreAggregation` also checks your role on the target deployment at call time: the
role must allow **Build pre-aggregations** or **Edit deployment** on that deployment
([deployment permissions][ref-deployment-permissions]), or **Manage deployments
(account-wide)**. These are the same permissions that allow builds on the
Pre-Aggregations page. Without one of them, the call fails, even on a dev branch.

| Tool | Description | Access |
| - | - | - |
| `getPreAggregationStatus` | Lists the data model's pre-aggregations with their definitions and, for each, how many partitions exist, how many were built, when the newest build landed, and the exact error if a build failed. Pass `branchName` to check a dev branch's pre-aggregations instead of the deployed model's. | Read-only |
| `buildPreAggregation` | Queues an on-demand build of one pre-aggregation and returns once it is accepted. The build runs asynchronously. Pass `branchName` to build against a dev branch's definition. | Write |

Together these close the loop on pre-aggregation work: a query alone cannot prove a rollup
was used, and external pre-aggregations fail in configuration-specific ways — a missing
export bucket, denied bucket permissions — that only an actual build surfaces. Call
`buildPreAggregation`, then poll `getPreAggregationStatus` to see whether the partitions
built or to read the failure.

> [!NOTE]
>
> `buildPreAggregation` runs real queries against your data warehouse and, for external
> pre-aggregations, writes through the export bucket. It consumes warehouse resources, so
> expect a cost per build.

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

![](https://lgo0ecceic.ucarecd.net/102c3c3e-3657-42aa-8d3d-2029ca21115c/)

### Build a dashboard

Four of the dashboard tools build a new dashboard, and they are designed to be used in
order. `readWorkbook`, `readReport`, `updateReport`, and `deleteReport` inspect and
change one that already exists. `listWorkspaceItems` finds it, and `moveWorkspaceItem`,
`createFolder`, `renameFolder`, and `deleteFolder` organize the workspace folders those
workbooks and dashboards live in.

**1. Create the workbook**

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. If you were given a link to its dashboard, call
`listWorkspaceItems` with the link as `url` first to get the `workbookId`.

**2. Create a report per chart**

Call `createReport` once per chart, KPI tile, or table, passing the `workbookId` and
the SQL query that powers it. Each call returns a `reportId`.

**3. Lay out the dashboard**

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.

**4. Publish**

Review the draft, then call `publishDashboard` to make it live. This also prompts for
confirmation. It returns the dashboard URL.

Anyone with the workbook open in the dashboard builder sees each change as soon as the
agent saves it, and anyone with the published dashboard open sees each publish, without
reloading — see [Live updates](https://docs.cube.dev/docs/explore-analyze/dashboards#live-updates).

To change a dashboard later, call `readWorkbook` first and edit on top of the current
draft rather than overwriting it. To change one chart rather than the layout, call
`readReport` on the widget's `reportId` and edit it with `updateReport` — that keeps the
id, so every widget pointing at it keeps rendering.

### 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.
Before committing, verify the change returns the right data: call `runQuery` with the same
`branchName` and check the numbers, since a compiling model can still return wrong results.
Review the result with `getDataModelChanges`, then see [Ship a model
edit](#ship-a-model-edit) to land the change and make it live.

To review a branch you didn't author — a colleague's feature branch, say — call
`getBranchDiff` with its name instead. It compares against the deploy branch and returns
the full changed-file list even when the patch itself is trimmed.

### Ship a model edit

Once `writeDataModelFile` edits compile and `runQuery` confirms they return the right
data, call `commitDataModelChanges` to land them on the branch the dev branch forked
from — read [How model edits stay safe](#how-model-edits-stay-safe) first if that
branch is the deploy branch. Use `commitToNewBranch` instead to put them on a new
branch, optionally with a pull request.
Either way, use `switchUserBranch` to point your own Cube UI at the result so you can
see it. `mergeToDefaultBranch` is the publish step: it makes the branch live for
everyone, so call it only when you want the change in production — no tool reverts it
afterwards. If an edit isn't working out, `discardDataModelChanges` throws it away
instead of committing it; it resets the dev branch only, so it is not an undo for a merge.

### Verify a pre-aggregation

After adding or changing a pre-aggregation, call `getPreAggregationStatus` to see whether
its partitions exist and when they were last built. If nothing has been built yet — or you
want to confirm an external pre-aggregation's export bucket actually works — call
`buildPreAggregation`, then poll `getPreAggregationStatus` again. A failed build reports
the exact error, which is usually a configuration problem rather than a modeling one;
`getDeploymentEnv` will tell you whether the expected variables (`CUBEJS_DB_EXPORT_BUCKET`
and friends) are set.

## 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 <id> 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**.
* **`Deployment <id> is served by the Cube MCP endpoint <endpoint>, which this session cannot reach`**: The deployment is served by a different endpoint from the one this connection signed in on. Add a connector for that endpoint — see [Deployments in more than one region](#deployments-in-more-than-one-region). If the client already uses that endpoint, reconnect it so it signs in there again.

[ref-roles]: https://docs.cube.dev/admin/users-and-permissions/roles-and-permissions.md

[ref-api-keys]: https://docs.cube.dev/admin/account-billing/api-keys.md

[ref-audit-log]: https://docs.cube.dev/admin/monitoring/audit-log.md

[ref-custom-roles]: https://docs.cube.dev/admin/users-and-permissions/custom-roles.md#global-permissions

[ref-deployment-permissions]: https://docs.cube.dev/admin/users-and-permissions/custom-roles.md#deployment-permissions

[ref-pre-aggregations]: https://docs.cube.dev/docs/pre-aggregations/using-pre-aggregations.md

[ref-sql-api]: https://docs.cube.dev/reference/core-data-apis/sql-api

[ref-agent-security-context]: https://docs.cube.dev/docs/explore-analyze/workbooks/querying-data.md#asking-the-agent-for-a-security-context

[ref-workbooks]: https://docs.cube.dev/docs/explore-analyze/workbooks

[ref-dashboards]: https://docs.cube.dev/docs/explore-analyze/dashboards

[ref-period-comparison]: https://docs.cube.dev/docs/explore-analyze/workbooks/querying-data.md#period-over-period-comparison

[ref-dev-mode]: https://docs.cube.dev/docs/data-modeling/dev-mode.md

[ref-reviewing-changes]: https://docs.cube.dev/docs/data-modeling/data-model-ide.md#reviewing-changes

[ref-folders]: https://docs.cube.dev/docs/organize-content/folders.md

[ref-deleting-folders]: https://docs.cube.dev/docs/organize-content/folders.md#deleting-folders


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