# Cube.dev MCP for AI Agents MCP

> Cube.dev MCP connects your AI client directly to a semantic data layer, letting you query complex data warehouses using natural language. Instead of writing boilerplate SQL or navigating multiple dashboards, your agent executes queries, inspects generated SQL code, and manages data model metadata instantly. You get consistent metrics and high-performance insights without knowing the underlying database structure.

## Overview
- **Category:** brain-trust
- **Price:** Free
- **Tags:** semantic-layer, data-modeling, sql-api, rest-api, pre-aggregations

## Description

This MCP gives your AI client a direct line into your data warehouse's semantic layer. Think of it as bypassing all the manual setup—you don't need to know if your data lives in Snowflake or BigQuery, just what you want to know about it.

It lets your agent run complex queries by translating natural language directly into reliable metrics and dimensions. You can debug models instantly by asking the MCP to show the raw SQL that was generated for a query. Need to check performance? You can trigger background jobs to pre-aggregate data, ensuring your dashboards stay fast even when querying huge datasets.

It's all managed through Vinkius, which makes connecting this power source simple. Your agent doesn't just retrieve numbers; it understands the structure of your entire data model—the cubes and views—letting you explore metadata right from the chat window. This is how you get reliable answers to tricky business questions without writing a single line of SQL.

## Tools

### check_live
Confirms whether the Cube deployment is currently active and accessible.

### check_ready
Checks if a specific Cube deployment has completed its initial setup process.

### convert_query
Translates standard SQL queries into the specialized REST API format required by Cube.dev.

### execute_cube_sql
Runs a raw, custom SQL query against the database for deep data investigation or testing purposes.

### generate_meta_token
Creates a temporary JSON Web Token (JWT) needed to access the Metadata API when using Cube Cloud.

### get_entity
Retrieves detailed metadata for one specific cube or view definition.

### get_meta
Provides a list of general metadata covering all available cubes and views in the data model.

### get_pre_aggregation_job_status
Retrieves the current status (running, failed, completed) of background pre-aggregation jobs.

### get_sql
Displays the actual SQL code that Cube.dev generates when running a query, useful for debugging data discrepancies.

### list_data_sources
Lists all external databases or services that are currently configured and connected to the Cube instance.

### list_deployments
Retrieves a list of all available deployments if you are using Cube Cloud infrastructure.

### list_entities
Shows an overview listing of every cube and view defined in the semantic layer.

### list_environments
Lists all supported environments (e.g., staging, production) for a given deployment using Cube Cloud.

### load_query
Executes the primary query function to return aggregated data results based on natural language parameters.

### trigger_pre_aggregation_job
Initiates a background job build to pre-calculate and optimize metrics for faster future querying.

## Prompt Examples

**Prompt:** 
```
What were our total sales last quarter, grouped by product status?
```

**Response:** 
```
**Sales Report: Q3 2024**

| Product Status | Total Revenue |
| :--- | :--- |
| Completed | $1.2M |
| Pending | $85k |
| Cancelled | $12k |

The highest volume came from 'Completed' orders, particularly those related to the Premium line.
```

**Prompt:** 
```
Show me how the system calculates the active user count.
```

**Response:** 
```
**Underlying Query Logic**

```sql
SELECT 
  count(DISTINCT users.user_id) AS active_users
FROM orders o
JOIN users u ON o.user_id = u.user_id
WHERE o.created_at >= '2024-12-01' AND o.created_at < '2025-01-01'
```
This confirms that the calculation correctly counts unique users who placed an order in December.
```

**Prompt:** 
```
I need to check if pre-aggregations are running for the marketing cube.
```

**Response:** 
```
**Pre-Aggregation Job Status**

*Job ID: 8b3c4d2e*
*Cube: Marketing Metrics*
*Status: Running*
*Estimated Completion Time: ~15 minutes*

Please wait a few moments, or check the status again using your agent.
```

## Capabilities

### Execute Aggregated Data Queries
Run complex reports using measures, dimensions, and filters by invoking the load_query tool.

### Debug Raw SQL Code
Use tools like get_sql or execute_cube_sql to see or run raw SQL queries against your database for deep investigation.

### Inspect Data Model Metadata
Retrieve details about cubes, views, and segments using get_meta to understand the data structure without leaving your chat interface.

### Manage Performance Jobs
Trigger and check the status of background pre-aggregation builds using trigger_pre_aggregation_job.

### Examine Data Sources and Deployments
List configured data sources (list_data_sources) or manage cloud infrastructure details like deployments (list_deployments).

## Use Cases

### Calculating year-over-year growth for a Product Line
A Product Manager needs to compare Q3 2024 sales against Q3 2023. Instead of writing complex date logic, they ask the agent directly. The MCP uses `load_query` and handles all the necessary filtering and aggregation to deliver the comparative report.

### Finding out why a key metric dropped last week
An Analytics Engineer notices 'Active Users' dipped suddenly. They ask the agent, prompting it to use `get_sql` to show the underlying query logic. By inspecting the generated SQL, they pinpoint that a specific dimension filter was incorrectly applied.

### Setting up performance for a new executive dashboard
The team is building a board with dozens of widgets. Before launching, an engineer triggers `trigger_pre_aggregation_job` on the core 'Sales' cube. This proactively builds necessary indexes and aggregates, ensuring the dashboards run smoothly when launched.

### Understanding how different data sources connect
A new team member joins and needs to know what data is available. They ask the agent for metadata, prompting it to use `get_meta` or `list_entities`. The MCP returns a structured list of all cubes (like 'Orders' or 'Users') and their definitions.

## Benefits

- Stop fighting boilerplate SQL. Instead of crafting complex `SELECT` statements, the agent handles the syntax, allowing you to focus purely on business logic.
- Maintain metric consistency across your organization. By querying through a semantic layer, every user gets the same definition for 'Total Revenue,' regardless of who writes the query.
- Save hours debugging data models. If a number looks wrong, use `get_sql` or `get_meta` to instantly see *why* that number was calculated, right in your chat.
- Keep dashboards lightning fast. Instead of letting slow queries bog down reporting, you can proactively trigger jobs using `trigger_pre_aggregation_job` to optimize performance.
- Manage infrastructure context easily. You can list deployments and environments (like staging or production) directly through the MCP, ensuring your agent is talking to the right data source.

## How It Works

The bottom line is: your AI client uses this MCP to handle all the complex connection logic between plain English questions and your underlying database structure.

1. Subscribe to the Cube.dev MCP and provide your unique API URL and Secret Token credentials.
2. Your AI client connects these tokens, allowing it to interact with Cube's semantic layer via the Vinkius framework.
3. You ask a natural language question (e.g., 'What were total sales last month?'), and the agent executes the necessary data functions and returns the final, structured answer.

## Frequently Asked Questions

**How does Cube.dev MCP help me get data insights without writing SQL?**
It translates your natural language questions into reliable database queries automatically. You just ask the question, and the agent handles all the complex code generation, giving you accurate answers directly.

**Can I use Cube.dev MCP to check if my data model is consistent?**
Yes. By using metadata tools like get_meta, the system shows you every cube and view available. This lets you verify your data model structure and understand how different pieces of data relate.

**What if my dashboard runs slowly? Can Cube.dev MCP fix that?**
It can help you optimize performance. You can trigger background pre-aggregation jobs, which calculate complex metrics ahead of time so your dashboards load instantly when needed.

**Does Cube.dev MCP only work for one type of database?**
No. Because it uses a semantic layer, it abstracts the underlying database complexity away from you. You focus on the data metrics, not the specific SQL dialect or connection details.

**Can I test my custom queries using Cube.dev MCP?**
Absolutely. It provides tools like execute_cube_sql that let your agent run raw, customized SQL against the database for deep testing and investigation purposes.