Metabase

Metabase MCP Server

Metabase includes a built-in Model Context Protocol (MCP) server that lets AI clients connect directly to a Metabase instance. It uses the Streamable HTTP transport and builds on Metabase's Agent API to expose tools for searching, navigating, querying, visualizing, and creating/updating content - all scoped to the connecting user's permissions.

Endpoint

The MCP server is available at:

https://{your-metabase.example.com}/api/metabase-mcp

The legacy /api/mcp path still works as an alias for existing clients, but /api/metabase-mcp is the canonical URL to advertise.

Connecting a client

Point any MCP-compatible client at the /api/metabase-mcp endpoint. For example, with Claude Code:

claude mcp add metabase https://{your-metabase.example.com}/api/metabase-mcp --transport streamable-http

For Claude Desktop, create a custom connector using the same URL.

For Cursor, open Settings > MCP and add a new server with the type set to streamable-http and the URL:

https://{your-metabase.example.com}/api/metabase-mcp

Authentication

MCP clients authenticate via OAuth 2.0. Metabase runs its own embedded OAuth server - no external provider is needed.

The flow for a first-time connection:

1. The client discovers Metabase's OAuth endpoints.
2. The client registers itself with Metabase.
3. The user is redirected to Metabase to log in and approve the connection.
4. The client receives an access token scoped to the user's Metabase permissions.

Browser-based sessions (cookie auth), API keys, and mb:full tokens hold no MCP scope, so they can connect but call no scoped tool.

Scopes

Access tokens are scoped to limit what tools a client can use:

Scope	Tools it grants
agent:content:read	browse_collection, browse_data, get_content, get_parameter_values, glossary, learn, search, and the catalog://metabase/fields data resource (see Resources)
agent:content:write	bookmark_content, collection_write, dashboard_write, document_write, duplicate_content, measure_write, metric_write, question_write, segment_write
agent:delivery:write	alert_write, subscription_write
agent:query:run	execute_query, refresh_ui_credential, render_drill_through, run_saved_question, visualize_query
agent:sql:run	execute_sql

A tool matches only the exact scope in the table. A wildcard such as * or agent:*, and the ::unrestricted sentinel, are not MCP scopes, so they grant no tool.

These scopes gate the MCP surface only. No REST endpoint may declare one as its :scope, so a new token issued to an MCP client grants nothing on the REST API.

The protected-resource metadata's scopes_supported and the scope of the 401 challenge both list every scope in the table, so a fresh connection asks for all of them. Some clients do not step up after a 403: a manual reconnect from Claude's connector settings registers a new client and asks for exactly what these list. When they listed only the baseline, that reconnect never offered writes, raw SQL, or delivery, and the user had no way to grant them (ENG-11089). The authorization server metadata advertises all of them too.

The baseline (agent:content:read agent:query:run) is locked on the consent screen: when a client requests one of these, the user cannot untick it. agent:query:run is in the baseline so that charts never need a step-up. Claude Desktop retries a tool after a step-up over a session that doesn't declare MCP Apps support, so a stepped-up visualize_query is refused and its chart never embeds.

A tool call or data resource read the token lacks a scope for is refused with HTTP 403 and a WWW-Authenticate: Bearer error="insufficient_scope" challenge whose scope lists the v2 scopes the token already holds plus the one required, so a client can step up. Each tool also declares its scope in securitySchemes, which is draft SEP-1488, supported by ChatGPT. It is not part of MCP 2025-03-26 (the version this server reports) or the final 2026-07-28 tools spec, so other clients discover the missing scope from the 403 instead. Inside a JSON-RPC batch the refusal is an in-band -32600 error instead. UI shell reads are never challenged: see Resources.

OAuth protected resource metadata is available at:

/.well-known/oauth-protected-resource/api/metabase-mcp

On the consent screen, every scope the client requested starts ticked, and the baseline scopes are also locked. Only the scopes left ticked are granted, and only for the token this authorization mints. An untick never touches a token the app already has. A scope left unticked is not remembered by Metabase. A later 403 can trigger another step-up in clients that support it. Other clients may require manual reauthorization. Each challenge's error_description ends with a note that the user must grant the permission on the consent screen.

Several clients replace the 403's error_description with their own text, so the initialize result's instructions explain scope failures to the model too: an auth error usually means a missing permission rather than an expired login, the model should name the failed tool or resource and the permission it requires, and the user grants it by reconnecting and leaving the permission ticked on the consent screen. The instructions are one static string, the same for every caller: there is no per-connection permission list.

Per-group tool access

On Enterprise instances with the ai_controls feature, an admin can narrow the surface per permissions group on Admin > AI > Usage controls > MCP tools access (shown whenever the MCP server is on, with or without an LLM provider). Each group has a row in mcp_group_permission saying whether its members may connect at all and, per tool name, the admin's explicit "yes" or "no"; a tool with no entry takes the default its author declared, so every deftool carries a required :default-access of :allowed or :denied and a tool released later gets exactly that default in every group until an admin overrides it. Entries are keyed by tool name, so renaming a tool needs :renamed-from with its former names (a stored entry under a former name still applies and the admin API presents it under the current name), or the author accepts that every admin's choice for it is discarded; metabase.mcp.v2.tool-names-test pins the live names so neither happens by accident. A user's effective policy is the tool_access of each group of theirs whose row enables MCP: MCP is on when any such group exists, and a tool is allowed when any of those groups resolves it to yes. The rows alone decide it, and they also record the permission mode: simple mode (Administrators, All Users, and All tenant users) or group-level mode (every other group), which is the state in which All Users has no row. A switch deletes the rows of the groups the new mode hides and seeds the groups it enables on entry that have no row (Data Analysts on entering group-level mode, All Users and All tenant users on leaving it), and PUT refuses a group the current mode hides, so no request reads a cached mode. The policy is applied on top of OAuth scopes in tools/list and tools/call (v2/registry.clj), and a user whose groups grant no access is refused at initialize and at resources/read (for sessions opened before MCP was turned off) with an error naming the fix. App-only tools (_meta {:ui {:visibility ["app"]}}, i.e. refresh_ui_credential) are not on the admin page: they are allowed while the policy allows any MCP Apps tool. Superusers and internal callers are never narrowed; OSS allows everything. On Enterprise the stored rows are enforced even without the ai_controls feature (an expired or unverifiable token keeps the restrictions an admin configured); the feature only gates the admin page and API. The resolver is permissions.clj (defenterprise, EE implementation in metabase-enterprise.mcp.permissions) and the admin API is /api/ee/ai-controls/mcp-permissions.

Available tools

Generated from the v2 registry (deftool). The scope named here is what the registry checks before the tool runs; some handlers check a further scope once they know what the call does - agent:sql:run when a source resolves to native SQL (question_write), and agent:query:run for the execution an alert or subscription defers (alert_write, subscription_write). Those refusals carry the same 403 insufficient_scope challenge. tools/list shows every tool whatever the token holds, and a token missing the scope may not call it.

Tool	Scope	Description
alert_write	agent:delivery:write	Create or update an alert: a notification sent on a schedule when a saved question's results meet a condition.
bookmark_content	agent:content:write	Add or remove a bookmark on content for the calling user — the same starred/favorites list the Metabase sidebar shows.
browse_collection	agent:content:read	Browse collections structurally — one uniform id over every partition: a numeric id, a 21-char entity_id, "root" (re-rooted per namespace), or "trash" (archived content, items mode only).
browse_data	agent:content:read	Browse the data hierarchy: databases → schemas → tables → fields.
collection_write	agent:content:write	Create, rename, move, archive, or restore a collection — the folders that hold questions, dashboards, models, and documents.
dashboard_write	agent:content:write	Create or update a dashboard and edit its layout with ordered ops.
document_write	agent:content:write	Create or update a document.
duplicate_content	agent:content:write	Copy a question, dashboard, or document into a collection — cheaper and safer than reading the original and re-creating it, and it preserves everything the read projections leave out.
execute_query	agent:query:run	The default way to answer a question from data: validate and execute a structured (MBQL) query, returning rows plus a query_handle.
execute_sql	agent:sql:run	Escape hatch: execute a raw SQL string against a database, returning rows plus a query_handle.
get_content	agent:content:read	Fetch content by {type, id} — the typed read for anything found via search or browse_collection.
get_parameter_values	agent:content:read	Fetch the valid values for one filter on a dashboard or saved question, so you filter with real values instead of guessing.
glossary	agent:content:read	Look up a business term as this Metabase instance defines it; the defined term names ride the tool's own description.
learn	agent:content:read	Read this server's task docs (skills) for the write dialects the schemas can't fully describe.
measure_write	agent:content:write	Create or update a measure: a named, reusable MBQL aggregation attached to one table, referenced inside another query's aggregation as ["measure", id].
metric_write	agent:content:write	Create or update a metric: a saved, reusable aggregation that lives in a collection and can be queried on its own or referenced from other queries.
question_write	agent:content:write	Create, update, or archive a saved question or model.
refresh_ui_credential	agent:query:run	Refresh the scoped credential used by a Metabase MCP App.
render_drill_through	agent:query:run	Render the drill-through visualization the user just navigated into.
run_saved_question	agent:query:run	Run a saved question (card) by numeric id or entity_id, returning rows inline.
search	agent:content:read	Find content across the Metabase instance by relevance.
segment_write	agent:content:write	Create or update a segment: a named, reusable MBQL filter attached to one table, referenced from other queries' filters.
subscription_write	agent:delivery:write	Create or update a dashboard subscription — scheduled delivery of a whole dashboard, e.g.
visualize_query	agent:query:run	Visualize a query as an interactive chart or table, rendered inline in the conversation.

execute_query returns row_limit rows per call (default 100, max 2000) — a page size, not a bound on the result. A truncated page reports truncated: true and, when the query has a total order, a next_cursor to pass back as cursor for the next page, until a page arrives with truncated: false. A query that wants only its first N rows carries limit: N in its stage (with an order-by); the server spends that limit down across pages, so the last page comes back complete with no cursor and pagination ends by itself.

Resources

The server exposes MCP resources so clients can fetch supplementary content by URI without inflating tool descriptions.

Resource URI	Scope	Description
ui://metabase/visualize-query.html	agent:query:run (UI credential only)	The MCP Apps iframe shell visualize_query points a capable client at.
ui://metabase/render-drill-through.html	agent:query:run (UI credential only)	The shell render_drill_through points at.
catalog://metabase/fields	agent:content:read	The dot-paths each content type accepts in fields arguments.

Every resource is listed whatever the token's scopes. A data resource, such as the fields catalog, is read only by a token holding its scope; otherwise the read gets the 403 insufficient_scope challenge described under Scopes. A UI shell is read by any token, because an MCP Apps host reads a tool's shell alongside the tool call, and if that read were refused, the host would not step up after the tool call's 403. The shells carry no data. A shell read by a token without the shell's scope never mints a UI credential. The chart data is gated by the tool call and by refresh_ui_credential (both agent:query:run), which the iframe needs before it can query anything. An unknown URI is a -32602 "Resource not found" error.

Skill packs are delivered through the learn tool rather than as resources.

Entity navigation is done with the get_content and browse_* tools rather than a URI scheme; the ui:// resources above exist only so a client that can render an iframe has something to mount.

Supported JSON-RPC methods

Method	Description
initialize	Initialize the MCP connection. Returns server capabilities and a session ID.
notifications/initialized	Client notification that initialization is complete.
tools/list	List available tools, whatever the token's scopes.
tools/call	Call a tool with arguments.
resources/list	List available resources, whatever the token's scopes.
resources/read	Read a resource by URI; a data resource needs its scope. Requires a session.
ping	Keepalive ping.

Requests can be sent individually or as a JSON-RPC batch. The server responds with JSON or SSE depending on the Accept header.

Architecture

The implementation lives in these files:

• transport.clj - The HTTP transport. Parses JSON-RPC requests, validates authentication and session headers, enforces origin checks (DNS rebinding protection), and dispatches to the appropriate method. Supports both JSON and SSE response formats.

• v2/api.clj - The tool surface handler. Wires the transport to the v2 tool + resource registries and defines method dispatch (tools/list, tools/call, resources/list, resources/read, ping).

• v2/registry.clj - The v2 tool registry. Tools self-register via deftool; the registry checks scopes, validates arguments, dispatches calls, and records usage.

• scope.clj - Scope matching logic. Exact matches only: wildcards, nil scopes, and the ::unrestricted sentinel match nothing.

Request flow

MCP client
  -> POST /api/metabase-mcp (JSON-RPC)
  -> Origin + session validation
  -> Auth: OAuth bearer token or browser session
  -> Scope check against requested tool
  -> Synthetic request to Agent API endpoint
  -> Response materialized as MCP content
  -> JSON or SSE back to client

Further reading

• MCP user docs
• Agent API source
• Model Context Protocol specification