diff --git a/docs/developer_docs/extensions/mcp-server.md b/docs/admin_docs/configuration/mcp-server.mdx similarity index 96% rename from docs/developer_docs/extensions/mcp-server.md rename to docs/admin_docs/configuration/mcp-server.mdx index 769ada1bc0d..22a80d645b3 100644 --- a/docs/developer_docs/extensions/mcp-server.md +++ b/docs/admin_docs/configuration/mcp-server.mdx @@ -1,7 +1,7 @@ --- title: MCP Server Deployment & Authentication hide_title: true -sidebar_position: 9 +sidebar_position: 14 version: 1 --- @@ -30,6 +30,10 @@ Superset includes a built-in [Model Context Protocol (MCP)](https://modelcontext This guide covers how to run, secure, and deploy the MCP server. +:::tip Looking for user docs? +See **[Using AI with Superset](/user-docs/using-superset/using-ai-with-superset)** for a guide on what AI can do with Superset and how to connect your AI client. +::: + ```mermaid flowchart LR A["AI Client
(Claude, ChatGPT, etc.)"] -- "MCP protocol
(HTTP + JSON-RPC)" --> B["MCP Server
(:5008/mcp)"] @@ -668,12 +672,13 @@ MCP_CSRF_CONFIG = { - **Secrets management** -- Store `MCP_JWT_SECRET`, database credentials, and API keys in environment variables or a secrets manager, never in config files committed to version control - **Scoped tokens** -- Use `MCP_REQUIRED_SCOPES` to limit what operations a token can perform - **Network isolation** -- In Kubernetes, restrict MCP pod network policies to only allow traffic from your AI client endpoints -- Review the **[Security documentation](./security)** for additional extension security guidance +- Review the **[Security documentation](/developer-docs/extensions/security)** for additional extension security guidance --- ## Next Steps -- **[MCP Integration](./mcp)** -- Build custom MCP tools and prompts via Superset extensions -- **[Security](./security)** -- Security best practices for extensions -- **[Deployment](./deployment)** -- Package and deploy Superset extensions +- **[Using AI with Superset](/user-docs/using-superset/using-ai-with-superset)** -- What AI can do with Superset and how to get started +- **[MCP Integration](/developer-docs/extensions/mcp)** -- Build custom MCP tools and prompts via Superset extensions +- **[Security](/developer-docs/extensions/security)** -- Security best practices for extensions +- **[Deployment](/developer-docs/extensions/deployment)** -- Package and deploy Superset extensions diff --git a/docs/developer_docs/sidebars.js b/docs/developer_docs/sidebars.js index babdcd41025..7926d80cf61 100644 --- a/docs/developer_docs/sidebars.js +++ b/docs/developer_docs/sidebars.js @@ -52,7 +52,6 @@ module.exports = { 'extensions/development', 'extensions/deployment', 'extensions/mcp', - 'extensions/mcp-server', 'extensions/security', 'extensions/tasks', 'extensions/registry', diff --git a/docs/docs/using-superset/using-ai-with-superset.mdx b/docs/docs/using-superset/using-ai-with-superset.mdx new file mode 100644 index 00000000000..3969042bcd2 --- /dev/null +++ b/docs/docs/using-superset/using-ai-with-superset.mdx @@ -0,0 +1,245 @@ +--- +title: Using AI with Superset +hide_title: true +sidebar_position: 5 +version: 1 +--- + + + +# Using AI with Superset + +Superset supports AI assistants through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). Connect Claude, ChatGPT, or other MCP-compatible clients to explore your data, build charts, create dashboards, and run SQL -- all through natural language. + +:::info +Requires Superset 5.0+. Your admin must enable and deploy the MCP server before you can connect. +See the **[MCP Server admin guide](/admin-docs/configuration/mcp-server)** for setup instructions. +::: + +--- + +## What Can AI Do with Superset? + +### Explore Your Data + +Ask your AI assistant to browse what's available in your Superset instance: + +- **List datasets** -- see all datasets you have access to, with filtering and search +- **Get dataset details** -- column names, types, available metrics, and filters +- **List charts and dashboards** -- find existing visualizations by name or keyword +- **Get chart and dashboard details** -- understand what a chart shows, its query, and configuration + +**Example prompts:** +> "What datasets are available?" +> "Show me the columns in the sales_orders dataset" +> "Find dashboards related to revenue" + +### Build Charts + +Describe the visualization you want and AI creates it for you: + +- **Create charts from natural language** -- describe what you want to see and AI picks the right chart type, metrics, and dimensions +- **Preview before saving** -- AI generates a preview so you can review before committing +- **Modify existing charts** -- update filters, change chart types, add metrics +- **Get Explore links** -- open any chart in Superset's Explore view for further refinement + +**Example prompts:** +> "Create a bar chart showing monthly revenue by region from the sales dataset" +> "Update chart 42 to use a line chart instead" +> "Give me a link to explore this chart further" + +### Create Dashboards + +Build dashboards from a collection of charts: + +- **Generate dashboards** -- create a new dashboard with a set of charts, automatically laid out +- **Add charts to existing dashboards** -- place a chart on an existing dashboard with automatic positioning + +**Example prompts:** +> "Create a dashboard called 'Q4 Sales Overview' with charts 10, 15, and 22" +> "Add the revenue trend chart to the executive dashboard" + +### Run SQL Queries + +Execute SQL directly through your AI assistant: + +- **Run queries** -- execute SQL with full Superset RBAC enforcement (you can only query data your roles allow) +- **Open SQL Lab** -- get a link to SQL Lab pre-populated with a query, ready to run and explore + +**Example prompts:** +> "Run this query: SELECT region, SUM(revenue) FROM sales GROUP BY region" +> "Open SQL Lab with a query to show the top 10 customers by order count" + +### Analyze Chart Data + +Pull the raw data behind any chart: + +- **Get chart data** -- retrieve the data a chart displays, with support for JSON, CSV, and Excel export formats +- **Inspect results** -- useful for verifying what a visualization shows or feeding data into other tools + +**Example prompts:** +> "Get the data behind chart 42" +> "Export chart 15 data as CSV" + +### Check Instance Status + +- **Health check** -- verify your Superset instance is up and the MCP connection is working +- **Instance info** -- get high-level statistics about your Superset instance (number of datasets, charts, dashboards) + +**Example prompts:** +> "Is Superset healthy?" +> "How many dashboards are in this instance?" + +--- + +## Connecting Your AI Client + +Once your admin has deployed the MCP server, connect your AI client using the instructions below. + +### Claude Desktop + +Edit your Claude Desktop config file: + +- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` +- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` +- **Linux**: `~/.config/Claude/claude_desktop_config.json` + +```json +{ + "mcpServers": { + "superset": { + "url": "http://localhost:5008/mcp" + } + } +} +``` + +Restart Claude Desktop. The hammer icon in the chat bar confirms the connection. + +If your admin has enabled JWT authentication, you may need to include a token: + +```json +{ + "mcpServers": { + "superset": { + "command": "npx", + "args": [ + "-y", + "mcp-remote@latest", + "http://your-superset-host:5008/mcp", + "--header", + "Authorization: Bearer YOUR_TOKEN" + ] + } + } +} +``` + +### Claude Code (CLI) + +Add to your project's `.mcp.json`: + +```json +{ + "mcpServers": { + "superset": { + "type": "url", + "url": "http://localhost:5008/mcp" + } + } +} +``` + +### ChatGPT + +1. Click your profile icon > **Settings** > **Apps and Connectors** +2. Enable **Developer Mode** in Advanced Settings +3. In the chat composer, press **+** > **Add sources** > **App** > **Connect more** > **Create app** +4. Enter a name and your MCP server URL +5. Click **I understand and continue** + +:::info +ChatGPT MCP connectors require a Pro, Team, Enterprise, or Edu plan. +::: + +Ask your admin for the MCP server URL and any authentication tokens you need. + +--- + +## Tips for Best Results + +- **Be specific** -- "Create a bar chart of monthly revenue by region from the sales dataset" works better than "Make me a chart" +- **Start with exploration** -- ask what datasets and charts exist before creating new ones +- **Review AI-generated content** -- always check chart configurations and SQL before saving or sharing +- **Use Explore for refinement** -- ask AI for an Explore link, then fine-tune interactively in the Superset UI +- **Check permissions if you get errors** -- AI respects Superset's RBAC, so you can only access data your roles allow + +--- + +## Available Tools Reference + +| Tool | Description | +|------|-------------| +| `health_check` | Verify the MCP server is running and connected | +| `get_instance_info` | Get instance statistics (dataset, chart, dashboard counts) | +| `get_schema` | Discover available charts, datasets, and dashboards with schema info | +| `list_datasets` | List datasets with filtering and search | +| `get_dataset_info` | Get dataset metadata (columns, metrics, filters) | +| `list_charts` | List charts with filtering and search | +| `get_chart_info` | Get chart metadata and configuration | +| `get_chart_data` | Retrieve chart data (JSON, CSV, or Excel) | +| `get_chart_preview` | Generate a chart preview (URL, ASCII, table, or Vega-Lite) | +| `generate_chart` | Create a new chart from a specification | +| `update_chart` | Modify an existing chart's configuration | +| `update_chart_preview` | Update a cached chart preview without saving | +| `list_dashboards` | List dashboards with filtering and search | +| `get_dashboard_info` | Get dashboard metadata and layout | +| `generate_dashboard` | Create a new dashboard with specified charts | +| `add_chart_to_existing_dashboard` | Add a chart to an existing dashboard | +| `execute_sql` | Run a SQL query with RBAC enforcement | +| `open_sql_lab_with_context` | Open SQL Lab with a pre-populated query | +| `generate_explore_link` | Generate an Explore URL for interactive visualization | + +--- + +## Troubleshooting + +### "Connection refused" or "Cannot connect" + +- Confirm the MCP server URL with your admin +- For Claude Desktop: fully quit the app (not just close the window) and restart after config changes +- Check that the URL path ends with `/mcp` (e.g., `http://localhost:5008/mcp`) + +### "Permission denied" or missing data + +- Superset's RBAC controls what you can access through AI, just like in the Superset UI +- Ask your admin to verify your roles and permissions +- Try accessing the same data through the Superset web UI to confirm your access + +### "Response too large" + +- Ask for smaller result sets: use filters, reduce `page_size`, or request specific columns +- Example: "Show me the top 10 rows from the sales dataset" instead of "Show me all sales data" + +### AI doesn't see Superset tools + +- Verify the connection in your AI client (e.g., the hammer icon in Claude Desktop) +- Ask the AI "What Superset tools are available?" to confirm the connection +- Restart your AI client if you recently changed the configuration