Repository navigation
docs(mcp): add API key auth, multi-client setup, and missing tools #1179
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
@@ -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 | ||||||||||||||||||||||
| <Tabs items={["Claude Code", "Codex", "Gemini CLI", "Open Code"]}> | ||||||||||||||||||||||
| <Tab value="Claude Code"> | ||||||||||||||||||||||
| ```bash title="terminal" | ||||||||||||||||||||||
| claude mcp add superset --transport http https://api.superset.sh/api/agent/mcp | ||||||||||||||||||||||
| ``` | ||||||||||||||||||||||
| </Tab> | ||||||||||||||||||||||
| <Tab value="Codex"> | ||||||||||||||||||||||
| ```bash title="terminal" | ||||||||||||||||||||||
| codex mcp add superset --url https://api.superset.sh/api/agent/mcp | ||||||||||||||||||||||
| ``` | ||||||||||||||||||||||
| </Tab> | ||||||||||||||||||||||
| <Tab value="Gemini CLI"> | ||||||||||||||||||||||
| ```bash title="terminal" | ||||||||||||||||||||||
| gemini mcp add --transport http superset https://api.superset.sh/api/agent/mcp | ||||||||||||||||||||||
| ``` | ||||||||||||||||||||||
| </Tab> | ||||||||||||||||||||||
| <Tab value="Open Code"> | ||||||||||||||||||||||
| ```bash title="terminal" | ||||||||||||||||||||||
| opencode mcp add | ||||||||||||||||||||||
| ``` | ||||||||||||||||||||||
| </Tab> | ||||||||||||||||||||||
| </Tabs> | ||||||||||||||||||||||
|
|
||||||||||||||||||||||
| Add to your `claude_desktop_config.json`: | ||||||||||||||||||||||
| ### Manual Configuration | ||||||||||||||||||||||
|
|
||||||||||||||||||||||
| <Tabs items={["SSE", "HTTP"]}> | ||||||||||||||||||||||
| <Tab value="SSE"> | ||||||||||||||||||||||
| ```json | ||||||||||||||||||||||
| Alternatively, you can manually configure the MCP server for each client: | ||||||||||||||||||||||
|
|
||||||||||||||||||||||
| <Tabs items={["Claude Code", "Claude Desktop", "Cursor", "Codex", "Gemini CLI", "Open Code"]}> | ||||||||||||||||||||||
| <Tab value="Claude Code"> | ||||||||||||||||||||||
| 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"] | ||||||||||||||||||||||
| } | ||||||||||||||||||||||
| } | ||||||||||||||||||||||
| } | ||||||||||||||||||||||
| } | ||||||||||||||||||||||
| ``` | ||||||||||||||||||||||
| </Tab> | ||||||||||||||||||||||
| <Tab value="HTTP"> | ||||||||||||||||||||||
| ```json | ||||||||||||||||||||||
| <Tab value="Claude Desktop"> | ||||||||||||||||||||||
| 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`: | |||||||||||||||||||||
| } | ||||||||||||||||||||||
| ``` | ||||||||||||||||||||||
| </Tab> | ||||||||||||||||||||||
| </Tabs> | ||||||||||||||||||||||
| <Tab value="Cursor"> | ||||||||||||||||||||||
| Add to `.cursor/mcp.json` in your project root: | ||||||||||||||||||||||
|
|
||||||||||||||||||||||
| ### Claude Code | ||||||||||||||||||||||
|
|
||||||||||||||||||||||
| <Tabs items={["SSE", "HTTP"]}> | ||||||||||||||||||||||
| <Tab value="SSE"> | ||||||||||||||||||||||
| ```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" | ||||||||||||||||||||||
| } | ||||||||||||||||||||||
| } | ||||||||||||||||||||||
| } | ||||||||||||||||||||||
| ``` | ||||||||||||||||||||||
| </Tab> | ||||||||||||||||||||||
| <Tab value="HTTP"> | ||||||||||||||||||||||
| ```bash | ||||||||||||||||||||||
| claude mcp add superset --transport http https://api.superset.sh/api/agent/mcp | ||||||||||||||||||||||
| <Tab value="Codex"> | ||||||||||||||||||||||
| Add to your `~/.codex/config.toml`: | ||||||||||||||||||||||
|
|
||||||||||||||||||||||
| ```toml title="config.toml" | ||||||||||||||||||||||
| [mcp_servers.superset] | ||||||||||||||||||||||
| url = "https://api.superset.sh/api/agent/mcp" | ||||||||||||||||||||||
| ``` | ||||||||||||||||||||||
| </Tab> | ||||||||||||||||||||||
| </Tabs> | ||||||||||||||||||||||
|
|
||||||||||||||||||||||
| ### Cursor | ||||||||||||||||||||||
| <Tab value="Gemini CLI"> | ||||||||||||||||||||||
| Add to your `.gemini/settings.json`: | ||||||||||||||||||||||
|
|
||||||||||||||||||||||
| Add to your Cursor MCP settings: | ||||||||||||||||||||||
|
|
||||||||||||||||||||||
| <Tabs items={["SSE", "HTTP"]}> | ||||||||||||||||||||||
| <Tab value="SSE"> | ||||||||||||||||||||||
| ```json | ||||||||||||||||||||||
| ```json title="settings.json" | ||||||||||||||||||||||
| { | ||||||||||||||||||||||
| "mcpServers": { | ||||||||||||||||||||||
| "superset": { | ||||||||||||||||||||||
| "url": "https://api.superset.sh/api/agent/sse" | ||||||||||||||||||||||
| "httpUrl": "https://api.superset.sh/api/agent/mcp" | ||||||||||||||||||||||
| } | ||||||||||||||||||||||
| } | ||||||||||||||||||||||
| } | ||||||||||||||||||||||
| ``` | ||||||||||||||||||||||
| </Tab> | ||||||||||||||||||||||
| <Tab value="HTTP"> | ||||||||||||||||||||||
| ```json | ||||||||||||||||||||||
| <Tab value="Open Code"> | ||||||||||||||||||||||
| 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. | ||||||||||||||||||||||
|
Comment on lines
140
to
+144
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Clarify that OAuth is default, not exclusive. This sentence now conflicts with the API key section below. Reword to indicate OAuth 2.1 is the default while API keys are also supported. ✏️ Suggested rewording-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.
+The MCP server supports OAuth 2.1 by default. When you first connect, you'll be prompted to authorize the connection in your browser. The token is scoped to your active organization.📝 Committable suggestion
Suggested change
🤖 Prompt for AI Agents |
||||||||||||||||||||||
|
|
||||||||||||||||||||||
| **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" | ||||||||||||||||||||||
| } | ||||||||||||||||||||||
| } | ||||||||||||||||||||||
| } | ||||||||||||||||||||||
| } | ||||||||||||||||||||||
| ``` | ||||||||||||||||||||||
|
|
||||||||||||||||||||||
| <Callout type="warn"> | ||||||||||||||||||||||
| 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. | ||||||||||||||||||||||
| </Callout> | ||||||||||||||||||||||
|
|
||||||||||||||||||||||
| **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" | ||||||||||||||||||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🧩 Analysis chain
🏁 Script executed:
cat -n apps/docs/content/docs/mcp.mdx | head -60Repository: superset-sh/superset
Length of output: 2200
🌐 Web query:
Open Code CLI opencode mcp add documentation syntax arguments💡 Result:
opencode mcp add— syntax & argumentsSyntax
Arguments / flags
mcp addtakes no positional arguments and is an interactive command that guides you through adding either a local or remote MCP server to your OpenCode configuration. [1]Where it’s stored / what it creates (config shape)
MCP servers are defined in your OpenCode config under
mcp(each server keyed by a unique name, with anenabledflag). [2]type: "local"and a requiredcommand: [...]. [2]type: "remote"and a requiredurl: "..."(optionallyheaders,oauth, etc.). [2]Sources: OpenCode CLI docs [1], OpenCode MCP servers docs [2].
Add clarification comment to explain that
opencode mcp addis interactive.The Open Code CLI's
mcp addcommand differs from other clients because it's interactive and takes no arguments—it prompts you for the server name and URL. The example should clarify this to avoid confusion.Suggested fix
📝 Committable suggestion
🤖 Prompt for AI Agents