Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

docs: ai updates (#74388)

Alex Yarosh3fe1b10013bc
diff --git a/docs/ai/agent-api.md b/docs/ai/agent-api.md
index e82df6d1fc1..a516b7307b4 100644
--- a/docs/ai/agent-api.md
+++ b/docs/ai/agent-api.md
@@ -1,14 +1,17 @@
---
title: Agent API
summary: The Agent API is a REST API for building headless, agentic BI applications on top of Metabase's semantic layer, scoped to an authenticated user's permissions.
-
---
# Agent API
-The [Agent API](../api.html#tag/apiagent) is a REST API for building headless, agentic BI applications on top of Metabase's semantic layer, scoped to an authenticated user's permissions.
+The [Agent API](../api.html#tag/apiagent) is a REST API for building headless, agentic BI applications on top of Metabase's semantic layer, scoped to an authenticated user's permissions. Agent API powers Metabase's MCP server.
+
+## Enable Agent API
+
+_Admin > AI > MCP_
-Admins enable the Agent API under **Admin > AI > MCP**. See [Agent API settings](./settings.md#agent-api-settings).
+Admins enable the Agent API under **Admin > AI > MCP**.
## Agent API endpoints and reference
diff --git a/docs/ai/mcp.md b/docs/ai/mcp.md
index 60eea1fc7cd..ce852de0283 100644
--- a/docs/ai/mcp.md
+++ b/docs/ai/mcp.md
@@ -9,9 +9,39 @@ summary: Connect MCP-compatible AI clients to Metabase to search, explore, and q
Metabase includes an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server (using Streamable HTTP transport) that lets AI clients connect directly to your Metabase, all scoped to the connecting person's permissions.
+# Enable MCP server
+
+_Admin > AI > MCP_
+
+MCP server and Agent API settings live on their own subpage. From **Admin > AI**, open the **MCP** tab in the left sidebar.
+
+Use the **MCP server** toggle to turn external access to the [MCP server](./mcp.md) on or off.
+
+### Supported MCP clients
+
+Under **Supported MCP clients**, switch on any clients you want to allow:
+
+- **Claude** (Claude Desktop and Claude on the web)
+- **Cursor and VS Code**
+- **ChatGPT**
+
+Toggling on a client automatically adds that client's sandbox domains to Metabase's CORS allowlist, which is what lets browser-based MCP clients make cross-origin requests to your Metabase.
+
+Some clients run outside the browser (like Claude Code on your own machine) and don't need a CORS allowlist entry. You can connect those clients without toggling anything on (assuming you've turned on the main MCP server setting).
+
+### Custom MCP client domains
+
+If you run a self-hosted MCP client, or a client that isn't in the supported list, add the client's domain to the **Custom MCP client domains** field. Separate values with a space, for example:
+
+```
+https://mcp.internal.example.com https://*.staging.example.com
+```
+
+The field accepts wildcards (`*`) for subdomains. Changes take effect in about a minute. Might be a good time to get up and pour yourself a glass of water.
+
## Connect an MCP client
-If your admin has turned on [your Metabase's MCP server](./settings.md#enable-mcp-server), all you need to do is point your MCP client at Metabase's MCP endpoint, `/api/mcp`. For example:
+If your admin has turned on [your Metabase's MCP server](#enable-mcp-server), all you need to do is point your MCP client at Metabase's MCP endpoint, `/api/mcp`. For example:
```
https://{your-metabase.example.com}/api/mcp
@@ -60,7 +90,7 @@ MCP server requests are handled by whatever AI client you're using (like a deskt
For example, if you ask your AI client to use your Metabase's MCP server "what's our q3 revenue," your client will interact with the MCP server to figure out which tools it needs to field your request. Your AI can decide that it needs to use the tool **construct_query** and **execute_query**, and what those queries might be. Then your client will call those tools for Metabase to run.
-You don't need to have an [AI provider](settings.md#supported-providers) configured in Metabase to use your Metabase's MCP server. If you _do_ have an AI provider configured in Metabase to power Metabot, that provider will _not_ be used for MCP server requests. MCP calls by your local client have no effect on token usage for your Metabase's AI connection.
+You don't need to have an [AI provider](settings.md#choose-ai-provider) configured in Metabase to use your Metabase's MCP server. If you _do_ have an AI provider configured in Metabase to power Metabot, that provider will _not_ be used for MCP server requests. MCP calls by your local client have no effect on token usage for your Metabase's AI connection.
## Available tools
diff --git a/docs/ai/overview.md b/docs/ai/overview.md
index 3e61f0c33c4..07f21dfd1cd 100644
--- a/docs/ai/overview.md
+++ b/docs/ai/overview.md
@@ -1,9 +1,9 @@
---
-title: AI in Metabase
+title: AI in Metabase overview
summary: Overview of all the ways you can use AI with Metabase.
---
-# AI in Metabase
+# AI in Metabase overview
AI in Metabase is optional. You can use Metabase without AI at all. But if you do want to use AI to interact with Metabase, we have you covered.
diff --git a/docs/ai/settings.md b/docs/ai/settings.md
index 9a503b7e3d1..8927aa39095 100644
--- a/docs/ai/settings.md
+++ b/docs/ai/settings.md
@@ -7,8 +7,6 @@ redirect_from:
# AI settings
-> AI features are available on [Metabase Cloud](https://www.metabase.com/features/metabot-ai) and on self-hosted Metabase, using either the Metabase AI service or your own AI provider API key.
-
_Admin > AI_
This page covers admin settings for AI features in Metabase, including [Metabot](./metabot.md). To limit _who_ can use Metabot, see [AI controls](./usage-controls.md).
@@ -19,16 +17,53 @@ AI features are available on both Metabase Cloud and self-hosted Metabase. To tu
1. Go to **Admin settings > AI**.
2. In **Connect to an AI provider**, choose a **Provider**:
- - **Metabase**: The Metabase AI service. Metabase picks a benchmarked, cost-effective model for you, and billing is managed through your Metabase account. Agree to the **Metabase AI add-on Terms of Service** and click **Connect**.
+ - **Metabase**: The Metabase AI service. Metabase picks a benchmarked, cost-effective model for you, and charges you on token usage. See [Choose AI provider](#choose-ai-provider)
- Another supported provider. See [bring your own API key](#bring-your-own-api-key).
3. Once connected, configure [Metabot](#configure-metabot) and other AI features below.
> The Metabase AI add-on only appears in your Metabase Store account after you've connected to the Metabase AI service in **Admin settings > AI**. If you're on a Pro trial and don't see the add-on in **Manage plan**, connect it from Admin first; the Store will reflect it after.
-## Bring your own API key
+## Choose AI provider
_Admin > AI_
+You can choose which AI provider and model is used to power Metabase's built-in agent.
+
+- If you're **self-hosting Metabase** and want to use Metabot, you need to [bring your own AI API key](#bring-your-own-api-key).
+- On **Metabase Cloud**, you can either [bring your own AI API key](#bring-your-own-api-key) or [use the Metabase AI Service](#metabase-ai-service).
+
+The AI provider that you specify in AI settings powers Metabase's built-in AI functionality, not the MCP server. [With the MCP server, your client provides the AI](mcp.md#with-the-mcp-server-your-client-provides-the-ai).
+
+### Metabase AI Service
+
+On Metabase Cloud, you can have us manage the AI for you with our AI Service.
+
+Metabase's AI Service is a good option if you don't have a preferred AI provider, or if you want to manage all your Metabase AI costs through Metabase. We (Metabase the company) select the models for you. We use internal benchmarks to determine which AI models work best for different tasks, and we're constantly iterating to improve performance.
+
+If you use Metabase's AI Service, you'll get charge based on token usage (in addition to your regular Metabase Cloud subscription fee). See [Pricing](https://www.metabase.com/pricing).
+
+To enable Metabase's AI Service on Metabase Cloud, you must me logged in to your Metabase instance with the email that matches the email for the admin of your [Metabase Store account](https://store.metabase.com).
+
+To use Metabase AI provider for your Metabot:
+
+1. Go to **Admin > AI > AI settings**.
+2. In **Connect to an AI provider**, choose **Metabase** as the provider.
+3. Agree to the terms of service.
+4. Click **Connect**.
+
+To disable Metabase AI provider and stop charges:
+
+1. Go to **Admin > AI > AI settings**.
+2. Under **Connected to Metabase**, click **Disconnect**.
+
+Any Metabase instance admin can disconnect the Metabase AI Service, even if they lack an admin account in the Metabase store.
+
+### Bring your own API key
+
+You can specify your own API key and model for Metabot from one of the supported providers. Currently, Metabase only supports models from Anthropic.
+
+If you're interested in Metabase supporting more AI providers, let us know by submitting a [feature request](../troubleshooting-guide/requesting-new-features.md).
+
To enable AI features with your own API key:
1. Go to **Admin > AI**.
@@ -37,17 +72,13 @@ To enable AI features with your own API key:
4. Click **Connect**.
5. Select a **Model** from the dropdown. Available models are fetched from the provider using your API key.
-When your connection is active, the provider card header shows **Connected to [provider]** (for example, "Connected to Anthropic") next to a green status dot. With your key connected, you get access to [Metabot](./metabot.md), [inline SQL generation](./metabot.md#inline-sql-editing), the [MCP server](./mcp.md), and the [Agent API](./agent-api.md).
+When your connection is active, the provider card header shows **Connected to [provider]** (for example, "Connected to Anthropic") next to a green status dot. With your key connected, you get access to [Metabot](./metabot.md), and [inline SQL generation](./metabot.md#inline-sql-editing).
To clear your provider connection, click **Disconnect**. Disconnecting removes the stored API key and turns off any AI features that depend on the provider.
-### Supported providers
-
-Currently, Metabase only supports models from Anthropic.
-
## Configure Metabot
-_Admin > AI > Metabot settings_
+_Admin > AI > AI settings_
![Metabot settings](./images/ai-settings.png)
@@ -104,42 +135,6 @@ When people open a new Metabot chat, Metabase shows a few suggested prompts base
Click **Regenerate suggested prompts** to generate a fresh set of prompts. You can also run individual prompts to test Metabot's answers, or delete prompts that aren't useful. The Internal and Embedded tabs each maintain their own set of suggestions, so regenerating on one tab doesn't affect the other.
-## Enable MCP server
-
-_Admin > AI > MCP_
-
-MCP server and Agent API settings live on their own subpage. From **Admin > AI**, open the **MCP** tab in the left sidebar.
-
-Use the **MCP server** toggle to turn external access to the [MCP server](./mcp.md) on or off.
-
-### Supported MCP clients
-
-Under **Supported MCP clients**, switch on any clients you want to allow:
-
-- **Claude** (Claude Desktop and Claude on the web)
-- **Cursor and VS Code**
-- **ChatGPT**
-
-Toggling on a client automatically adds that client's sandbox domains to Metabase's CORS allowlist, which is what lets browser-based MCP clients make cross-origin requests to your Metabase.
-
-Some clients run outside the browser (like Claude Code on your own machine) and don't need a CORS allowlist entry. You can connect those clients without toggling anything on (assuming you've turned on the main MCP server setting).
-
-### Custom MCP client domains
-
-If you run a self-hosted MCP client or one that isn't in the supported list, add its domain to the **Custom MCP client domains** field. Separate values with a space, for example:
-
-```
-https://mcp.internal.example.com https://*.staging.example.com
-```
-
-The field accepts wildcards (`*`) for subdomains. Changes take effect in about a minute. Might be a good time to get up and pour yourself a glass of water.
-
-## Agent API settings
-
-_Admin > AI > MCP_
-
-Use the **Agent API** toggle to turn external access to the [Agent API](./agent-api.md) on or off.
-
## Disable all AI features
The **Disable all AI features** toggle at the bottom of the AI features page is a master kill switch. When turned on, it hides all AI features across your instance — Metabot, inline SQL generation, the MCP server, the Agent API, and any embedded chat components — regardless of the individual toggles above.
@@ -190,19 +185,13 @@ In other words, to restrict what data Metabot can see for each person, simply ap
## Viewing Metabot usage
-If you're using the Metabase AI service, you can see how many Metabot requests people have made this month by going to **Admin > Settings > License**.
+If you're using the Metabase AI service, you can see how many Metabot requests people have made this month by going to **Admin > AI**.
If you aren't logged into the [Metabase Store](../cloud/accounts-and-billing.md), you'll need to log in to the store before you can view the usage. Once logged in to the store, go back to your Metabase and view the license page.
-The **Metabot AI requests used, this month (updated daily)** field shows how many requests your Metabase has used this month. Each message sent to Metabot counts as a request.
-
If you're using your own API key, you can track usage and costs through your AI provider's dashboard.
-## Choosing the AI model
-
-If you're using your own API key, you can choose which AI model Metabase uses when you [bring your own API key](#bring-your-own-api-key).
-
-When using the Metabase AI service, Metabase selects models automatically. We use internal benchmarks to determine which AI models work best for different tasks, and we're constantly iterating to improve performance.
+On Metabase Pro/Enterprise, you also get access to detailed [AI usage auditing](usage-auditing.md) with detailed breakdown of AI usage by user, tool, feature etc.
## Privacy
@@ -220,4 +209,13 @@ Metabot has access to your Metabase metadata and some data values to help answer
- **Sample field values**: When you ask questions like "Filter everyone from Wisconsin," Metabot might check the values in the state field to understand how the data is stored (like "WI" vs "Wisconsin"). See [syncs](../databases/sync-scan.md).
- **Timeseries data**: For chart analysis, Metabot might see the timeseries data used to draw certain visualizations, depending on the chart type.
-This data may be included when you [submit feedback](./metabot.md#giving-feedback-on-metabot-responses).
+When you [submit feedback](./metabot.md#giving-feedback-on-metabot-responses), the context for the conversation - including this metadata and conversation prompts - might be sent to Metabase.
+
+## Further reading
+
+- [Using Metabot](metabot.md)
+- [MCP server](mcp.md)
+- [AI access and usage controls](usage-controls.md)
+- [AI usage auditing](usage-auditing.md)
+- [Metabot customization](customization.md)
+- [Metabot system prompts](system-prompts.md)
diff --git a/docs/ai/start.md b/docs/ai/start.md
index 2591093e3e1..84fe839c7cb 100644
--- a/docs/ai/start.md
+++ b/docs/ai/start.md
@@ -4,8 +4,6 @@ title: "AI in Metabase"
# AI in Metabase
-> AI features are available on [Metabase Cloud](https://www.metabase.com/features/metabot-ai) and on self-hosted Metabase, using either the Metabase AI service or your own AI provider API key. Enable them from **Admin settings > AI**.
-
## [Metabot](./metabot.md)
Metabot is an AI assistant that helps you explore and analyze your data.
@@ -41,4 +39,3 @@ Chat with Metabot directly in Slack — ask questions, get charts, and manage su
## [AI usage auditing](./usage-auditing.md)
See how people are using the AI features in your Metabase.
-