> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcargo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Metabase

> Connect Metabase to run saved questions and SQL, sync question results into models, and give agents access to your Metabase.

## How to set up Metabase

### Authentication

Metabase authenticates with an API key:

1. In Metabase, go to **Admin** → **Settings** → **Authentication** → **API keys**
2. Create a key and assign it to a group. The key inherits that group's permissions, so give it a group that can see the databases and collections you want to reach from Cargo
3. Copy the key — Metabase only shows it once
4. In Cargo, enter:
   * **Instance URL**: the address of your Metabase, for example `https://mycompany.metabaseapp.com`
   * **API Key**: the key you just created

Cargo verifies the connection by listing the databases the key can see.

## Metabase actions

### Run question

Runs a saved question and returns its rows.

**Configuration:**

* **Question**: the saved question to run
* **Parameters** (optional): Metabase parameter objects, each with a `type`, a `target` and a `value`

Values are returned unformatted, so numbers stay numbers and dates stay dates rather than arriving as the strings shown in the Metabase interface.

### Run SQL

Runs a SQL query against a database connected to Metabase.

**Configuration:**

* **Database**: the target database
* **SQL**: the query to run

The API key's group needs native query permission on that database. Metabase caps this endpoint at 2000 rows; when a result hits the cap the action reports that it was truncated.

### Search entities

Searches questions, models, metrics, dashboards, collections and tables.

**Configuration:**

* **Query**: the search term
* **Entity types** (optional): restrict the search
* **Limit** (optional): defaults to 25, up to 100

## Metabase data models

### Fetch question

Syncs the rows of a saved question into a Cargo model.

**Configuration:**

* **Question**: the saved question to sync
* **ID column**: the column that uniquely identifies a row
* **Title column**: the column used as the record title

**Features:**

* **Full refresh**: each run replaces the model with a fresh snapshot, since Metabase exposes no cursor over a question's results
* **Minimum interval**: 1 hour between syncs

Metabase results have no identifier of their own, which is why you pick the ID column yourself. Choose one that is unique and stable across runs — a primary key from the underlying table, or the grouping column of an aggregate. If a run comes back with rows but no ID values, the sync fails on purpose rather than overwriting what was synced last time.

A question that returns 50,000 rows or more is rejected: add a filter or an aggregation to narrow it down.

Column names come from the question's columns and must contain only letters, numbers, underscores and spaces. Rename them in Metabase if a sync reports invalid columns.

## MCP server

Metabase hosts its own MCP server, so a Metabase connector can be attached directly to a Cargo agent. The agent gets Metabase's own tools: searching tables and metrics, reading entities, constructing and executing queries, running SQL, and creating questions and dashboards.

Before this works, a Metabase admin must turn the MCP server on under **Admin** → **AI** → **MCP**, and AI features must be enabled for the instance. If the connector authenticates but the agent cannot reach any tools, that setting is the first thing to check.

## Best practices

* Give the API key its own group with the narrowest permissions that cover your use case, rather than reusing an admin group
* Prefer saved questions over ad-hoc SQL for anything recurring: the question stays reviewable in Metabase and its columns are typed
* Aggregate in Metabase before syncing. Full refresh means every run pays for the whole result set, so a question returning a rolled-up few thousand rows beats one returning raw events
* Use the MCP server for exploratory questions from agents, and actions for the deterministic steps of a workflow