[manual] master -> master

_docs/master/README.md

@@ -159,8 +159,13 @@ Metabase's reference documentation.
 - [AI overview](./ai/start)
 - [Metabot](./ai/metabot)
 - [AI settings](./ai/settings)
+- [AI usage controls](./ai/usage-controls)
+- [AI usage auditing](./ai/usage-auditing)
+- [AI customization](./ai/customization)
+- [AI system prompts](./ai/system-prompts)
 - [Agent API](./ai/agent-api)
 - [MCP server](./ai/mcp)
+- [Metabot in Slack](./ai/metabot-slack)
 
 ### Exploration and organization
 

_docs/master/ai/agent-api.md

@@ -12,7 +12,13 @@ summary: 'The Agent API is a REST API for building headless, agentic BI applicat
 
 # Agent API
 
-The [Agent API](../api#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#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**.
 
 ## Agent API endpoints and reference
 

_docs/master/ai/customization.md

@@ -0,0 +1,49 @@
+---
+version: master
+has_magic_breadcrumbs: true
+show_category_breadcrumb: true
+show_title_breadcrumb: true
+category: Ai
+title: 'AI customization'
+source_url: 'https://github.com/metabase/metabase/blob/master/docs/ai/customization.md'
+layout: new-docs
+summary: 'Change how Metabot appears in Metabase for a branded look.'
+---
+
+# AI customization
+
+{% include plans-blockquote.html feature="AI customization" %}
+
+_Admin > AI > Customization_
+
+Admins can change how Metabot displays itself in Metabase.
+
+To navigate to the AI customization settings:
+
+1. Click the **grid** icon in the upper right.
+2. Click **Admin**.
+3. Go to the **AI** tab.
+4. Click on the **Customization** tab.
+
+These customizations are just surface-level. If you want to change the AI's behavior, check out [System prompts](./system-prompts).
+
+## Metabot's name
+
+Rename Metabot. The new name shows up everywhere Metabase refers to Metabot (sidebar, buttons, suggested prompts, empty states).
+
+## Metabot's icon
+
+Upload a custom icon. SVG or PNG with a transparent background gives the cleanest result. Max size is 1MB.
+
+## Show Metabot illustrations
+
+![Metabot illustrations](./images/metabot-illustrations.png)
+
+Once you've uploaded a custom icon, this toggle appears and controls whether the default decorative illustrations show in the Metabot chat sidebar and on the AI exploration page.
+
+## Further reading
+
+- [AI settings](./settings)
+- [AI usage controls](./usage-controls)
+- [AI system prompts](./system-prompts)
+- [Metabot](./metabot)

_docs/master/ai/mcp.md

@@ -16,15 +16,51 @@ summary: 'Connect MCP-compatible AI clients to Metabase to search, explore, and
 
 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) 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#mcp-server-settings), 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
 ```
 
-In Claude Code, for example, you can run `/mcp add metabase https://{your-metabase.example.com}/api/mcp --transport streamable-http` and Claude will handle the OAuth flow for you.
+In the terminal, for example, you can run the following command.
+
+```
+claude mcp add --transport http metabase https://{your-metabase-url}/api/mcp
+```
+
+Replacing {your-metabase-url} with your Metabase address. Once added, Claude Code will handle the OAuth flow for you:
 
 For Claude Desktop, you can create a [custom connector](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) by just giving it that URL to your Metabase's mcp endpoint.
 
@@ -55,6 +91,14 @@ Some explanation: OAuth discovery starts with Metabase returning a `WWW-Authenti
 
 If the site URL doesn't match an address your MCP client can reach, like if you're running Metabase in Docker and the site URL got auto-detected from an internal hostname like `metabase-dev:3000`, the client will register but fail the handshake. Your MCP client will typically report a connection failure rather than prompting you to authenticate (for example, Claude Code shows `✗ Failed to connect` rather than `! Needs authentication`).
 
+## With the MCP server, your client provides the AI
+
+MCP server requests are handled by whatever AI client you're using (like a desktop AI app or editor plugin). The MCP server just provides tools (like searching for an entity or running the query) for your AI.
+
+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#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
 
 Some clients (like Claude Desktop) will ask you to approve each tool the first time it's used. The MCP server builds on Metabase's [Agent API](./agent-api), and exposes the following tools. If you're building a custom integration and need full control, use the [Agent API](./agent-api) directly instead.
@@ -67,6 +111,8 @@ Some clients (like Claude Desktop) will ask you to approve each tool the first t
 - **construct_query**: Construct a query against a table or metric. Returns an opaque query string that can be executed with `execute_query`.
 - **execute_query**: Execute a previously constructed query and return the results with column metadata, row count, and execution time.
 - **query**: Query a table or metric and return results.
+- **create_question**: Create questions.
+- **create_dashboard**: Create dashboards.
 
 ## Use the MCP server with file-based development
 

_docs/master/ai/metabot-slack.md

@@ -12,15 +12,15 @@ summary: 'Chat with Metabot directly in Slack to ask questions about your data,
 
 # Metabot in Slack
 
-![Metabot in Slack](./metabot-slack.png)
+![Metabot in Slack](./images/metabot-slack.png)
 
 Chat with [Metabot](./metabot) in Slack. Direct message Metabot for private analysis, or mention @Metabot in a channel to collaborate with your team.
 
 ## What Metabot can do
 
 From Slack you can ask Metabot to:
 
-- **Find existing content**: Search your Metabase for questions, and dashboards. Metabot links you directly to the content in your Metabase.
+- **Find existing content**: Search your Metabase for questions and dashboards. Metabot links you directly to the content in your Metabase.
 - **Answer questions**: Create ad-hoc queries from natural language to answer your questions on the spot. You can click the link to save the question in Metabase.
 - **Show charts and tables**: Render static visualizations or tabular results in Slack. You can copy table results or download them as TSV.
 - **Work with CSVs**: [Upload a CSV](../databases/uploads) to Metabase, then ask follow-up questions about the data.
@@ -68,7 +68,7 @@ Some caveats:
 - For goal-based alerts, the goal line must already be configured and saved on the question. Metabot can't add goal lines.
 - Metabot can't modify or delete existing alerts or subscriptions.
 - Alerts and subscriptions are delivered to the Slack channel where the conversation takes place. You can't redirect them to a different channel or to email.
-- Alerts can only be set on questions not metrics or ad-hoc queries.
+- Alerts can only be set on questions, not metrics or ad-hoc queries.
 
 ## Notes on privacy
 

_docs/master/ai/metabot.md

@@ -22,16 +22,17 @@ To set up Metabot, see [Metabot settings](./settings).
 
 ## What Metabot can do
 
-Metabot can help you to:
+Here's a non-exhaustive list of things Metabot can help with:
 
-- [AI exploration](#ai-exploration).
+- [Answer data questions asked with natural language](#ai-exploration).
 - [Create a chart using the query builder](#how-metabot-uses-the-query-builder) from a natural language query.
 - [Generate SQL in the native editor](../questions/native-editor/writing-sql) from natural language. (Currently, only SQL is supported.)
 - [Edit SQL directly in the native editor](#inline-sql-editing).
 - [Analyze a chart](#analyze-charts-with-metabot).
 - [Fix errors in SQL code](#have-metabot-fix-sql-queries).
-- Answer questions from our documentation (as in, the literature you're reading right now).
-- [Chat with Metabot in Slack](./metabot-slack).
+- [Generate transforms](../data-studio/transforms/transforms-overview#use-metabot-to-generate-code-for-transforms)
+- [Generate charts in documents](../documents/introduction)
+- [Answer questions from Slack](./metabot-slack).
 
 Like with all generative AI, you'll always need to double-check results.
 
@@ -136,8 +137,6 @@ When answering questions in AI exploration, Metabot searches a limited set of co
 
 Metabot is getting smarter all the time, but there are some things it can't do yet:
 
-- **Custom expressions.** Metabot can't use [custom expressions](../questions/query-builder/expressions-list) in query builder questions.
-- **Multi-level aggregation.** Metabot is limited to a single level of aggregation and grouping.
 - **SQL variables.** Metabot can't generate SQL queries that include [SQL parameters](../questions/native-editor/sql-parameters) (like filters or field filters).
 - **Goal lines.** Metabot can't add [goal lines](../questions/visualizations/line-bar-and-area-charts#goal-lines) to charts.
 - **Chart formatting.** Metabot can't change visualization settings like colors, axis labels, or number formatting.

_docs/master/ai/overview.md

@@ -0,0 +1,68 @@
+---
+version: master
+has_magic_breadcrumbs: true
+show_category_breadcrumb: true
+show_title_breadcrumb: true
+category: Ai
+title: 'AI in Metabase overview'
+source_url: 'https://github.com/metabase/metabase/blob/master/docs/ai/overview.md'
+layout: new-docs
+summary: 'Overview of all the ways you can use AI with 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.
+
+Here are the different ways to use AI with Metabase:
+
+- [Metabot](#metabot)
+- [MCP server](#mcp-server)
+- [Agent-driven file-based development workflow](#agent-driven-development-workflow)
+
+## Metabot
+
+**Best for: daily tasks in Metabase; granular control over people's AI usage.**
+
+Metabot is Metabase's built-in AI agent. Metabot can help you with most daily tasks around Metabase, like answering questions about your data, creating queries, generating SQL code, explaining charts, or creating Documents. If you're embedding Metabase into your product, you can get the Metabot agent through the [AI chat component](../embedding/components#ai-chat). See [non-exhaustive list of things Metabot can do](metabot#what-metabot-can-do), as well as its [limitations](metabot#current-limitations).
+
+**Controls:** Metabot will only see what the person using it can see. Metabot also comes with additional permission controls and usage limits so that you control who can use which Metabot tools (e.g. chat vs SQL generation) and how many tokens they can spend.
+
+**Provider**: Choose from:
+
+- Metabase's own AI Service (available as an add-on exclusively for Metabase Cloud)
+- Third-party models via an API key (Anthropic models only for now).
+
+**Plans**: available on all plans. You can only use Metabase's AI Service on Metabase Cloud.
+
+See [full docs for Metabot](metabot) and [embedded AI chat](../embedding/components#ai-chat).
+
+## MCP server
+
+**Best for: asking ad-hoc, ephemeral questions; combining data from Metabase with data from other tools.**
+
+Connect your favorite third-party AI tool - like Claude or Codex - to the Metabase MCP server. MCP servers are designed for answering in-the-moment questions like "hey btw what's our q3 revenue?" Metabase's MCP server is also useful when combined with other MCP servers. For example, you can ask Claude a question about your customers that combines data from Metabase, your CRM, and your support ticket platform.
+
+Compared to the built-in Metabot, MCP server has somewhat restricted functionality (for example, it can't generate code or build transforms for now). See [the ever-expanding list of MCP server tools](mcp#available-tools).
+
+**Controls**: Metabase MCP server requires people to authenticate into Metabase, and all the responses it provides will be scoped to their permissions. However, unlike built-in Metabot, MCP server doesn't come with granular control over which _tools_ people can use, or disable MCP server altogether.
+
+**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).
+
+**Plans**: MCP server is available on all plans.
+
+See [full docs for MCP server](mcp).
+
+## Agent-driven development workflow
+
+**Best for: developers creating stuff that other people will use.**
+
+Use a coding agent like Claude Code to understand your database's metadata, generate Metabase content as YAML files locally, verify the schema, then sync and import the generated content into your production Metabase. Sky's the limit on what you can accomplish.
+
+**Controls**: Only admins can sync content to Metabase instances.
+
+**Provider**: Everything is handled by your coding agent of choice.
+
+**Plans**: Agent-driven workflows require a Pro/Enterprise plan.
+
+See [full docs for agent-driven workflow](./file-based-development)