Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
164 changes: 130 additions & 34 deletions apps/docs/content/docs/mcp.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Comment on lines +40 to +44

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

cat -n apps/docs/content/docs/mcp.mdx | head -60

Repository: superset-sh/superset

Length of output: 2200


🌐 Web query:

Open Code CLI opencode mcp add documentation syntax arguments

💡 Result:

opencode mcp add — syntax & arguments

Syntax

opencode mcp add

Arguments / flags

  • None. mcp add takes 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 an enabled flag). [2]

  • Local MCP uses type: "local" and a required command: [...]. [2]
  • Remote MCP uses type: "remote" and a required url: "..." (optionally headers, oauth, etc.). [2]

Sources: OpenCode CLI docs [1], OpenCode MCP servers docs [2].


Add clarification comment to explain that opencode mcp add is interactive.

The Open Code CLI's mcp add command 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
- opencode mcp add
+ opencode mcp add  # follow prompts for server name and URL
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
<Tab value="Open Code">
```bash title="terminal"
opencode mcp add
```
</Tab>
<Tab value="Open Code">
🤖 Prompt for AI Agents
In `@apps/docs/content/docs/mcp.mdx` around lines 40 - 44, Clarify that the Open
Code CLI command opencode mcp add is interactive and accepts no inline arguments
by updating the mcp.mdx example: add a short explanatory sentence near the Tab
block (the example showing the opencode mcp add command) stating that the
command will prompt for server name and URL interactively rather than taking
arguments, so users know to run it and then respond to prompts.

</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": {
Expand All @@ -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
}
}
}
Expand All @@ -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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

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

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
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.
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.
### 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.
🤖 Prompt for AI Agents
In `@apps/docs/content/docs/mcp.mdx` around lines 140 - 144, Update the opening
sentences to make OAuth 2.1 the default but not exclusive: replace "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." with a single clear statement like "By default, the MCP server
uses OAuth 2.1; when you first connect you'll be prompted to authorize in your
browser and the token is scoped to your active organization; API keys are also
supported for headless environments." Ensure this change appears in the OAuth
section immediately before the "API Key Authentication" heading so the
relationship between defaults and alternatives is clear.


**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
Expand All @@ -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 |
Expand All @@ -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:
Expand All @@ -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"
Loading