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) are also supported and receive unrestricted scopes.

Scopes

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

Wildcard patterns (e.g. agent:*) match any scope with that prefix.

Clients start with a baseline. The protected-resource metadata's scopes_supported and the scope of the 401 challenge both list only agent:content:read agent:query:run agent:resource:read: a fresh connection can read, query, and chart. Writes (agent:content:write), raw SQL (agent:sql:run), and alerts and subscriptions (agent:delivery:write) need a step-up. The surface still accepts every scope in the table, and the authorization server metadata still advertises all of them.

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, the baseline scopes are ticked and locked, and every other scope the client requested starts unticked. Only the scopes the user ticks 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 tick 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 ticking permissions on the consent screen. Because every optional permission starts unticked, the instructions tell the model to have the user tick every permission they want, not only the new one. The instructions are one static string, the same for every caller: there is no per-connection permission list.

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.