From 7bd8939e30dafc6a0eef437adfa1a6d2a5af3a9b Mon Sep 17 00:00:00 2001 From: Satya Patel Date: Tue, 3 Feb 2026 17:45:07 -0800 Subject: [PATCH] docs(mcp): add API key auth, multi-client setup, and missing tools - Restructure setup section with CLI Options (Claude Code, Codex, Gemini CLI, Open Code) and Manual Configuration tabs per client - Add API key authentication section with generation and usage docs - Add missing tools: update_workspace, start_claude_session, start_claude_subagent - Add AI Sessions category to capabilities and tools tables - Verify config formats against each client's official docs --- apps/docs/content/docs/mcp.mdx | 164 ++++++++++++++++++++++++++------- 1 file changed, 130 insertions(+), 34 deletions(-) diff --git a/apps/docs/content/docs/mcp.mdx b/apps/docs/content/docs/mcp.mdx index 58964faeae0..608da6c0bb3 100644 --- a/apps/docs/content/docs/mcp.mdx +++ b/apps/docs/content/docs/mcp.mdx @@ -12,32 +12,67 @@ Superset provides an [MCP (Model Context Protocol)](https://modelcontextprotocol | Category | Tools | |----------|-------| | **Tasks** | Create, update, list, get, delete tasks | -| **Workspaces** | Create, switch, delete, list workspaces | +| **Workspaces** | Create, update, switch, delete, list, navigate workspaces | | **Devices** | List devices, projects, and app context | | **Organization** | List members and task statuses | +| **AI Sessions** | Start autonomous Claude sessions and subagents | ## Setup -Superset supports two MCP transports: **SSE** (Server-Sent Events) and **Streamable HTTP**. Both work identically—choose based on your client's preference. +### CLI Options -### Claude Desktop + + +```bash title="terminal" +claude mcp add superset --transport http https://api.superset.sh/api/agent/mcp +``` + + +```bash title="terminal" +codex mcp add superset --url https://api.superset.sh/api/agent/mcp +``` + + +```bash title="terminal" +gemini mcp add --transport http superset https://api.superset.sh/api/agent/mcp +``` + + +```bash title="terminal" +opencode mcp add +``` + + -Add to your `claude_desktop_config.json`: +### Manual Configuration - - -```json +Alternatively, you can manually configure the MCP server for each client: + + + +Add a `.mcp.json` to your project root. Claude Code auto-discovers this file and handles OAuth authentication. + +```json title=".mcp.json" { "mcpServers": { "superset": { - "url": "https://api.superset.sh/api/agent/sse" + "type": "http", + "url": "https://api.superset.sh/api/agent/mcp", + "oauth": { + "clientId": "claude-code", + "authorizationUrl": "https://api.superset.sh/api/auth/mcp/authorize", + "tokenUrl": "https://api.superset.sh/api/auth/mcp/token", + "scopes": ["openid", "profile", "email"] + } } } } ``` - -```json + +Add to your `claude_desktop_config.json`: + +```json title="claude_desktop_config.json" { "mcpServers": { "superset": { @@ -48,46 +83,51 @@ Add to your `claude_desktop_config.json`: } ``` - + +Add to `.cursor/mcp.json` in your project root: -### Claude Code - - - -```bash -claude mcp add superset --transport sse https://api.superset.sh/api/agent/sse +```json title=".cursor/mcp.json" +{ + "mcpServers": { + "superset": { + "url": "https://api.superset.sh/api/agent/mcp" + } + } +} ``` - -```bash -claude mcp add superset --transport http https://api.superset.sh/api/agent/mcp + +Add to your `~/.codex/config.toml`: + +```toml title="config.toml" +[mcp_servers.superset] +url = "https://api.superset.sh/api/agent/mcp" ``` - - -### Cursor + +Add to your `.gemini/settings.json`: -Add to your Cursor MCP settings: - - - -```json +```json title="settings.json" { "mcpServers": { "superset": { - "url": "https://api.superset.sh/api/agent/sse" + "httpUrl": "https://api.superset.sh/api/agent/mcp" } } } ``` - -```json + +Add to your `opencode.json`: + +```json title="opencode.json" { - "mcpServers": { + "$schema": "https://opencode.ai/config.json", + "mcp": { "superset": { - "type": "http", - "url": "https://api.superset.sh/api/agent/mcp" + "type": "remote", + "url": "https://api.superset.sh/api/agent/mcp", + "enabled": true } } } @@ -99,6 +139,52 @@ Add to your Cursor MCP settings: The MCP server uses OAuth 2.1. When you first connect, you'll be prompted to authorize the connection in your browser. The token is scoped to your active organization. +### API Key Authentication + +For headless environments, CI/CD pipelines, or scripts where browser-based OAuth isn't practical, you can authenticate with an API key instead. + +**Generating an API key:** + +1. Open the Superset desktop app +2. Go to **Settings > API Keys** +3. Click **Create API Key** +4. Copy the key (it starts with `sk_live_`)—you won't be able to see it again + +**Using the API key:** + +Pass the API key as a Bearer token in the `Authorization` header: + +``` +Authorization: Bearer sk_live_your_api_key_here +``` + +MCP clients that support custom headers can use this directly. For Claude Code, set the header in your `.mcp.json`: + +```json +{ + "mcpServers": { + "superset": { + "type": "http", + "url": "https://api.superset.sh/api/agent/mcp", + "headers": { + "Authorization": "Bearer sk_live_your_api_key_here" + } + } + } +} +``` + + +API keys grant full access to your organization. Keep them secret and never commit them to version control. Use environment variables or secrets managers for CI/CD. + + +**When to use which method:** + +| Method | Best for | +|--------|----------| +| OAuth 2.1 | Interactive use — Claude Desktop, Claude Code, Cursor | +| API Key | Headless/CI — scripts, automation, pipelines | + ## Available Tools ### Task Management @@ -117,6 +203,7 @@ The MCP server uses OAuth 2.1. When you first connect, you'll be prompted to aut | Tool | Description | |------|-------------| | `create_workspace` | Create a new git worktree workspace | +| `update_workspace` | Update workspaces (rename) | | `switch_workspace` | Switch to a different workspace | | `delete_workspace` | Delete a workspace | | `list_workspaces` | List all workspaces on a device | @@ -131,6 +218,13 @@ The MCP server uses OAuth 2.1. When you first connect, you'll be prompted to aut | `get_app_context` | Get current app state (active workspace, pathname) | | `list_members` | List organization members | +### AI Sessions + +| Tool | Description | +|------|-------------| +| `start_claude_session` | Start an autonomous Claude Code session for a task. Creates a new workspace with its own git branch and launches Claude with the task context. | +| `start_claude_subagent` | Start a Claude Code subagent in an existing workspace. Adds a new terminal pane instead of creating a new workspace. | + ## Example Usage Once connected, you can ask your AI agent to: @@ -139,3 +233,5 @@ Once connected, you can ask your AI agent to: - "List all my assigned tasks" - "Create a new workspace for the auth feature" - "Show me who's online in my team" +- "Start a Claude session on my MacBook to work on the auth task" +- "Spin up a subagent to fix the failing tests"