MCP Server

Overview

Superset provides an MCP (Model Context Protocol) server that lets AI agents interact with your tasks, workspaces, and devices programmatically.

Capabilities

Setup

CLI Options

claude mcp add superset --transport http https://api.superset.sh/api/agent/mcp

codex mcp add superset --url https://api.superset.sh/api/agent/mcp

gemini mcp add --transport http superset https://api.superset.sh/api/agent/mcp

opencode mcp add

[2m┌[0m  Add MCP server
[2m│[0m
[2m◇[0m  Location
[2m│[0m  [36mCurrent project[0m
[2m│[0m
[2m◇[0m  Enter MCP server name
[2m│[0m  [36msuperset[0m
[2m│[0m
[2m◇[0m  Select MCP server type
[2m│[0m  [36mRemote[0m
[2m│[0m
[2m◇[0m  Enter MCP server URL
[2m│[0m  [36mhttps://api.superset.sh/api/agent/mcp[0m
[2m│[0m
[2m◇[0m  Does this server require OAuth authentication?
[2m│[0m  [36mYes[0m
[2m│[0m
[2m◇[0m  Do you have a pre-registered client ID?
[2m│[0m  [36mNo[0m
[2m│[0m
[2m└[0m  [32mMCP server added successfully[0m

Manual Configuration

Alternatively, you can manually configure the MCP server for each client:

{
  "mcpServers": {
    "superset": {
      "type": "http",
      "url": "https://api.superset.sh/api/agent/mcp"
    }
  }
}

{
  "mcpServers": {
    "superset": {
      "type": "http",
      "url": "https://api.superset.sh/api/agent/mcp"
    }
  }
}

{
  "mcpServers": {
    "superset": {
      "url": "https://api.superset.sh/api/agent/mcp"
    }
  }
}

[mcp_servers.superset]
url = "https://api.superset.sh/api/agent/mcp"

{
  "mcpServers": {
    "superset": {
      "httpUrl": "https://api.superset.sh/api/agent/mcp"
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "superset": {
      "type": "remote",
      "url": "https://api.superset.sh/api/agent/mcp"
    }
  }
}

Authentication

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:

{
  "mcpServers": {
    "superset": {
      "type": "http",
      "url": "https://api.superset.sh/api/agent/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_your_api_key_here"
      }
    }
  }
}

When to use which method:

Available Tools

Task Management

Workspace Management

Device & Organization

AI Sessions

Chat Integration

In the built-in chat panel, use the /mcp slash command to see your workspace's configured MCP servers — their names, transport type (local/remote), and current state (enabled/disabled/invalid). This reads from your workspace MCP config (.mastracode/mcp.json or .mcp.json).

Example Usage

Once connected, you can ask your AI agent to:

• "Create a task for fixing the login bug"
• "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"
• "Start a Codex session in my auth workspace with the prompt 'fix the failing tests'"
• "Spin up a subagent to fix the failing tests"