Merge Unified's Metabase integration Merge Agent Handler's Metabase MCP server

Connect your AI Agents to Metabase in minutes

Merge lets you securely connect your agents to Metabase and thousands of tools instantly

Start building for free

Read docs

Metabase

Learn more about Merge Agent Handler

Available tools

list_cards

List cards (saved questions) with client-side pagination (the Metabase API returns the full list; this tool slices it for you) and server-side filters. Returns a lightweight summary per card — call getcard for its datasetquery/visualization_settings. Use search to filter by name instead of paging through everything.

get_card

Get a card (saved question) by ID. Use list_cards or search to find valid IDs.

create_card

Create a new card (saved question). Use listdatabases to find a valid database id for datasetquery, and listcollections to find a valid collectionid (omit to place it in the root collection).

update_card

Update a card's name, description, query, display, collection, or archived status. Use listcards or search to find the cardid. Use listcollections to find a valid collectionid.

delete_card

Permanently and irreversibly delete a card by ID (hard delete — cannot be undone). To move it to Trash instead, where it can be restored, use updatecard with archived=true. Use listcards or search to find the card_id.

run_card_query

Run a card's saved query and return its result rows and columns, truncated to limit rows (default 500) to avoid overflowing context. Use listcards or search to find the cardid. Set ignore_cache=true to force a fresh run instead of a cached result. Pass parameters to run a parameterized question with different template-tag/filter values instead of its saved defaults.

list_collections

List collections (folders that organize dashboards and questions) with client-side pagination (the Metabase API returns the full list; this tool slices it for you). Use this to find valid collectionid values for createdashboard and create_card. Set archived=true to list archived collections instead of active ones.

get_collection

Get a collection by ID. Use list_collections to find valid IDs.

list_dashboards

List dashboards with server-side pagination and filters, including by collectionid. Items are a lightweight summary — call getdashboard for a dashboard's filter/parameter definitions. Use search to filter by name instead of paging through everything.

get_dashboard

Get a dashboard by ID. Use list_dashboards or search to find valid IDs.

create_dashboard

Create a new dashboard. Use listcollections to find a valid collectionid, or omit it to place the dashboard in the root collection.

update_dashboard

Update a dashboard's name, description, collection, or archived status. Use listdashboards or search to find the dashboardid. Use listcollections to find a valid collectionid.

delete_dashboard

Permanently and irreversibly delete a dashboard by ID (hard delete — cannot be undone). To move it to Trash instead, where it can be restored, use updatedashboard with archived=true. Use listdashboards or search to find the dashboard_id.

list_databases

List databases connected to this Metabase instance with client-side pagination (the Metabase API returns the full list; this tool slices it for you). Use this to find valid databaseid values for createcard's dataset_query. Connection credentials are never returned.

get_database

Get a database by ID. Use list_databases to find valid IDs. Connection credentials are never returned.

list_groups

List permission groups with client-side pagination (the Metabase API returns the full list; this tool slices it for you). Use this to find valid groupid values for listusers' group_id filter.

get_group

Get a permission group by ID, including its member list (user id/email/name per member). Use listgroups to find valid groupid values.

search

Search dashboards, cards (questions), collections, tables, and databases by name substring, with server-side filters and server-side pagination. Use this instead of listdashboards/listcards when you know part of the name.

list_users

List Metabase users with server-side pagination and filters. Use this to find valid user IDs. Use listgroups to find a valid groupid to filter by.

get_user

Get a Metabase user by ID. Use list_users to find valid IDs.

validate_credential

Validate the Metabase instance URL and API key by fetching the current user.

View all tools by creating a free account See more tools

How to set up Merge Agent Handler

In an mcp.json file, add the configuration below, and restart Cursor.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5      "headers": {
6        "Authorization": "Bearer yMt*****"
7      }
8    }
9  }
10}
11

Copy Code

Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.

Make sure Claude is using the Node v20+.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "mcp-remote@latest",
8        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9        "--header",
10        "Authorization: Bearer ${AUTH_TOKEN}"
11      ],
12      "env": {
13        "AUTH_TOKEN": "yMt*****"
14      }
15    }
16  }
17}

Copy Code

Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.

Learn more in the official documentation ↗

1{
2    "mcpServers": {
3      "agent-handler": {
4        "command": "npx",
5        "args": [
6          "-y",
7          "mcp-remote@latest",
8          "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9          "--header",
10          "Authorization: Bearer ${AUTH_TOKEN}"
11        ],
12        "env": {
13          "AUTH_TOKEN": "<ah-production-access-key>"
14        }
15      }
16    }
17  }

Copy Code

In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".

You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.

Learn more in the official documentation ↗

1{
2  "inputs": [
3    {
4      "type": "promptString",
5      "id": "agent-handler-auth",
6      "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7      "password": true
8    }
9  ],
10  "servers": {
11    "agent-handler": {
12      "type": "stdio",
13      "command": "npx",
14      "args": [
15        "-y",
16        "mcp-remote@latest",
17        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18        "--header",
19        "Authorization: Bearer ${input:agent-handler-auth}"
20      ]
21    }
22  }
23}

Copy Code

FAQs on using Merge's Metabase MCP server

What is a Metabase MCP?

It's an MCP server that lets your agents access data and functionality from Metabase via tools. Your agents can invoke these tools to run a saved question, pull a dashboard's results, execute a native SQL query, list available databases, and more.

Metabase ships its own official MCP server, scoped to the connecting user's Metabase permissions. You can also connect through a third-party platform like Merge Agent Handler, which puts Metabase behind the same endpoint as every other tool your agents use.

How can I use the Metabase MCP server?

The use cases naturally depend on the agent you've built, but here are a few common ones:

Scheduled metric digest: On a daily or weekly schedule, an agent runs a saved question in Metabase, formats the latest numbers, and posts them to a Slack channel or email digest so the team doesn't have to log in to check

Ad-hoc question answering from live data: When someone asks "what was signup volume last week" in Slack, an agent translates it into a Metabase query, runs it against the live database, and replies inline with the answer

Dashboard summary posted to Slack: When a dashboard refreshes, an agent pulls the latest card results, writes a plain-language summary of what changed, and posts it to a Slack channel for stakeholders

Anomaly flagging on a saved question's results: An agent periodically re-runs a saved question, compares the new results against historical values, and opens a ticket or pings a channel when a metric moves outside its expected range

What are popular tools for Metabase's MCP server?

Here are some of the most commonly used tools:

run_card: executes a saved question, what Metabase calls a "card," and returns its result set. this is the tool an agent reaches for when it needs the live numbers behind a specific metric or report

run_native_query: executes an ad-hoc SQL query against a connected database. useful when the question isn't already saved as a card and needs a custom query

get_dashboard: retrieves a dashboard's layout along with the current results for every card it contains. good for pulling a full snapshot of a report rather than a single metric

list_databases: returns the databases connected to a Metabase instance, along with schema details. agents call this first when they need to know what data is even available to query

search_cards: finds saved questions by keyword or natural-language description. handy when an agent knows roughly what metric it needs but not the exact card name

list_collections: lists the collections that organize dashboards and questions into folders. agents use this to navigate a large Metabase instance and locate the right resources by team or project

What makes Merge Agent Handler's Metabase MCP server better than alternative Metabase MCP servers?

Since Metabase already ships its own official MCP server, the difference comes down to what you get once agents are actually running in production:

Enterprise-grade security and DLP: Merge Agent Handler includes built-in data loss prevention controls that let you block or redact sensitive fields before they reach an agent. For Metabase, this means you can prevent raw customer or revenue data returned by a native SQL query from being exposed even when the agent has broad read access

Managed authentication and credentials: Merge stores and refreshes Metabase credentials on your behalf. You never expose raw API keys or OAuth tokens to an agent or manage token rotation manually

Real-time observability and audit trail: Every tool call made against Metabase is logged with timestamp, tool name, input parameters, and response metadata. You can audit exactly what an agent read or wrote without instrumenting anything yourself

Tool Packs and controlled access: Tool Packs let you bundle specific Metabase tools with tools from other connectors into a single MCP endpoint, scoped to a specific use case. An agent gets exactly the tools it needs, nothing more

How can I start using Merge Agent Handler's Metabase MCP server?

You can take the following steps:

1. Create or log into your Merge Agent Handler account.

2. Install the Merge CLI by running pipx install merge-api, then run merge configure to link the CLI to your Merge account and merge login to authenticate your session.

3. Register the Agent Handler MCP server with Claude Code by running claude mcp add --transport http agent-handler https://ah-api.merge.dev/mcp, then open Claude Code and run /mcp to confirm agent-handler appears with a connected status.

4. Select agent-handler from the MCP list. This opens a browser window where you select which integrations to authenticate. Choose Metabase and complete the auth flow. Merge stores and manages the credentials going forward.

5. Open a Claude Code session and start querying Metabase data directly. The first time you use a Metabase tool, a Magic Link may appear to complete connector authentication.

If you want to connect Merge Agent Handler's Metabase MCP with internal or customer-facing agentic products, you can follow the steps in our docs.

Can employees use Merge to connect their AI tools to Metabase?

Yes, Merge for Workforce lets your employees connect Claude, ChatGPT, Microsoft Copilot, Cursor, Codex, and other MCP-compatible AI tools to Metabase without bypassing IT governance.

Instead of setting up direct connections with personal credentials that IT can't monitor or revoke, each employee authenticates through Merge and gets individual credentials tied to their identity. An analyst can ask their AI to pull a dashboard's latest numbers, run a saved question, or summarize a metric trend, all within IT-defined permissions.

IT also provisions access by role or group via SCIM. A data analyst, for example, gets Metabase access to run saved questions, Snowflake access to query warehouse tables, and Slack access to post summaries to a channel, while a finance manager gets Metabase access to pull revenue dashboards, NetSuite access to reconcile transactions, and Google Sheets access to export reporting data.

Every tool call an employee's AI makes to Metabase is also inspected against your DLP rules and logged to a searchable audit trail, giving security teams full visibility into what data was accessed and by whom.