The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
docs - mcp tools access controls (#84167)
Jeff Bruemmer691ae2990623
diff --git a/docs/ai/images/mcp-tools-access.png b/docs/ai/images/mcp-tools-access.pngnew file mode 100644index 00000000000..28025421d94Binary files /dev/null and b/docs/ai/images/mcp-tools-access.png differdiff --git a/docs/ai/mcp.md b/docs/ai/mcp.mdindex c7601328822..ea65bdaf2cc 100644--- a/docs/ai/mcp.md+++ b/docs/ai/mcp.md@@ -23,7 +23,7 @@ Replace `{your-metabase.example.com}` with your Metabase's URL. Admins can alsoYour client will direct you to an authentication page for your Metabase.-Once authenticated, you can approve or block the tools in your client (not in your Metabase).+Once authenticated, you can approve or block the tools in your client. On [Pro and Enterprise plans](https://www.metabase.com/pricing), admins can also [limit which tools each group can use](./usage-controls.md#mcp-tools-access).Connected a client before Metabase 0.64? It'll ask you to sign in again after you upgrade.@@ -79,6 +79,8 @@ One of your Metabase admins will still need to have [turned on your Metabase's MThe MCP server gives your agent tools for searching, browsing, querying, and creating content in your Metabase. For the full list and the permission each one needs, see [MCP server tools](./mcp-tools.md).+On [Pro and Enterprise plans](https://www.metabase.com/pricing), admins can choose which of these tools each group can use. See [MCP tools access](./usage-controls.md#mcp-tools-access).+## Using the MCP serverThe MCP server will return results as either text or an inline chart, depending on the question you asked.diff --git a/docs/ai/overview.md b/docs/ai/overview.mdindex 0cf5f39392d..21debc5232d 100644--- a/docs/ai/overview.md+++ b/docs/ai/overview.md@@ -38,7 +38,7 @@ Connect your favorite third-party AI tool - like Claude or Codex - to the MetabaCompared to the built-in Metabot, the MCP server has a narrower set of tools. See [MCP server tools](mcp-tools.md) for what it can do.-**Controls**: People log in to Metabase to use the MCP server, and everything it returns is scoped to their permissions. Admins can [turn the MCP server off](mcp.md#turn-on-the-mcp-server) for everyone.+**Controls**: People log in to Metabase to use the MCP server, so the MCP server can only do what their permissions allow. Admins can [turn the MCP server off](mcp.md#turn-on-the-mcp-server) for everyone. On [Pro and Enterprise plans](https://www.metabase.com/pricing), admins can also [choose which MCP tools each group can use](usage-controls.md#mcp-tools-access).**Provider**: Requests to Metabase's MCP server are handled by the provider you choose to connect to the MCP server (e.g. Claude, Cursor, etc).diff --git a/docs/ai/start.md b/docs/ai/start.mdindex 5949dd42c00..e6655d8c7c3 100644--- a/docs/ai/start.md+++ b/docs/ai/start.md@@ -22,7 +22,7 @@ What data Metabase sends to AI providers and MCP clients, and what Metabase coll## [AI usage controls](./usage-controls.md)-Control who can use Metabot, and set token and message limits.+Control who can use Metabot, which MCP tools each group can use, and set token and message limits.## [AI customization](./customization.md)diff --git a/docs/ai/usage-controls.md b/docs/ai/usage-controls.mdindex a88b5dfbc74..b056ca0fb46 100644--- a/docs/ai/usage-controls.md+++ b/docs/ai/usage-controls.md@@ -1,6 +1,6 @@---title: AI usage controls-summary: Control who can use Metabot, and cap token or message usage by instance, group, or tenant.+summary: Control who can use Metabot and which MCP tools each group can use, and cap token or message usage by instance, group, or tenant.---# AI usage controls@@ -9,9 +9,10 @@ summary: Control who can use Metabot, and cap token or message usage by instance_Admin > AI > Usage controls_-Once you've connected an AI provider (see [AI settings](./settings.md)), you can control who can use Metabot and set usage budgets.+Once you've connected an AI provider (see [AI settings](./settings.md)), you can control who can use Metabot and set usage budgets. If you've [turned on the MCP server](./mcp.md#turn-on-the-mcp-server), you can also choose which MCP tools each group can use.- [AI feature access](#ai-feature-access): which groups can use Metabot, and which of its tools.+- [MCP tools access](#mcp-tools-access): which MCP tools each group's AI clients can use.- [AI usage limits](#ai-usage-limits): token or message caps by instance, group, or tenant.## AI feature access@@ -29,6 +30,57 @@ These controls are granular. If you uncheck SQL generation but leave Chat and NL[Tenant](../embedding/tenants.md) groups follow the same model as regular groups.+## MCP tools access++_Admin > AI > Usage controls > MCP tools access_++++MCP tools access lets you choose which [MCP server](./mcp.md) tools each group's AI clients can use. For example, you can let your analysts run raw SQL from Claude or Cursor, and give everyone else only the tools that read content.++By default, everyone can use every MCP tool. The **MCP tools access** page only shows up once you've [turned on the MCP server](./mcp.md#turn-on-the-mcp-server).++Tool access doesn't replace other permissions. People still need the usual [data](../permissions/data.md) and [collection](../permissions/collections.md) permissions, and their client still needs the right [permission scope](./mcp.md#permission-scopes).++### Allow or block MCP tools++[MCP tools](./mcp-tools.md) are grouped under scope rows, named after the [permission scope](./mcp.md#permission-scopes) each tool needs:++| Scope row | Permission scope |+| -------------- | ---------------------- |+| **Read** | `agent:content:read` |+| **Query** | `agent:query:run` |+| **Raw SQL** | `agent:sql:run` |+| **Write** | `agent:content:write` |+| **Deliveries** | `agent:delivery:write` |++Check or uncheck tools as needed, and click **Save changes**.++The **Administrators** column always has every box checked: admins always get every tool.++### How Metabase applies MCP tool access++- **Groups add up.** A person can use a tool if any of their groups allows it.+- **Changes apply on the next request.** Metabase checks tool access on every request, so you don't need to restart Metabase, and people don't need to reconnect their clients.+- **Blocked tools are hidden.** Metabase leaves blocked tools out of the tool list it gives a client. If a client calls a blocked tool anyway, Metabase refuses, and tells the person to ask an admin to enable the tool under **Admin > AI > Usage controls > MCP tools access**.+- **People with no tools can't connect.** People need to be in at least one group with access to tools to the MCP server.+- **Blocking `execute_sql` also blocks saving SQL questions.** People who can't use the `execute_sql` tool can't save SQL questions with the `question_write` tool either.+- **Tool access stays if you change plans.** If you change to a plan without AI controls, Metabase keeps applying the MCP tool access you set.++### Set MCP tool access for each group++By default, the grid has two columns: **Administrators** and **All Users**. Every person who isn't an admin gets the tools you allow for **All Users**. If you use [tenants](../embedding/tenants.md), the **Tenant groups** tab does the same for **All tenant users**.++To give different groups different tools, switch to group-level permissions:++1. Set up your [groups](../people-and-groups/managing.md#groups).+2. Click **Switch to group-level permissions**.+3. Click **Switch** to confirm.++In group-level mode, **All Users** and **All tenant users** groups lose MCP tool access. That way, groups only get the tools you allow them. Admins always get every tool. When you switch, Metabase gives the [Data Analysts](../people-and-groups/managing.md#data-analysts) group every tool, but you can change its tools like any other group's.++To switch back, click the gear icon, then **Remove group-level access**, then **Remove access from all groups**. Switching back to one set of tools for everyone deletes the tool access you set for each group, and gives **All Users** (and **All tenant users**) every tool.+## AI usage limits_Admin > AI > Usage controls > AI usage limits_