Skip to main content

​
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