MCP Server

This document covers MCP v2. The v1 server is deprecated but still available at https://api.superset.sh/api/agent/mcp for existing integrations.

Overview

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

Capabilities

Category	Operations
Tasks	list, get (by id or slug), create, update, delete
Workspaces	list (filterable by host), create on a host, delete
Automations	list, get metadata, get/set prompt body, create, update metadata, pause, resume, run on demand, list runs, delete
Projects	list projects, create from a Git URL or local repo path
Hosts	list hosts (registered machines) you have access to

Setup

CLI Options

terminal

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

terminal

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

terminal

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

Run opencode mcp add and follow the interactive prompts:

terminal

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/v2/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

terminal

amp mcp add --workspace superset https://api.superset.sh/api/v2/agent/mcp

Manual Configuration

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.

.mcp.json

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

Add to your claude_desktop_config.json:

claude_desktop_config.json

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

Add to .cursor/mcp.json in your project root:

.cursor/mcp.json

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

Add to your ~/.codex/config.toml:

config.toml

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

Add to your .gemini/settings.json:

settings.json

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

Add to your opencode.json:

opencode.json

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

Add to .amp/settings.json in your project root:

.amp/settings.json

{
  "amp.mcpServers": {
    "superset": {
      "url": "https://api.superset.sh/api/v2/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:

Open the Superset desktop app
Go to Settings > API Keys
Click Create API Key
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/v2/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

Tasks

Tool	Description
`tasks_list`	List tasks with optional filters (status, priority, assignee, free-text search)
`tasks_get`	Get one task by UUID or slug
`tasks_create`	Create a task in the active organization
`tasks_update`	Update fields on an existing task
`tasks_delete`	Hard-delete a task by UUID

Workspaces

Tool	Description
`workspaces_list`	List workspaces, optionally filtered by host
`workspaces_create`	Create a workspace on a host (branch-scoped git worktree)
`workspaces_delete`	Delete a workspace by UUID; idempotent

Automations

Tool	Description
`automations_list`	List automations the calling user owns
`automations_get`	Get one automation's metadata (prompt body omitted)
`automations_get_prompt`	Fetch the full markdown prompt for one automation
`automations_create`	Schedule a recurring agent run with an RFC 5545 RRULE
`automations_update`	Update metadata (name, schedule, agent, host); use `automations_set_prompt` to change the prompt
`automations_set_prompt`	Replace the full markdown prompt body
`automations_pause`	Pause an automation (schedule stops firing)
`automations_resume`	Resume a paused automation
`automations_run`	Dispatch an automation immediately, outside its schedule
`automations_logs`	List recent runs for an automation
`automations_delete`	Delete an automation

Projects

Tool	Description
`projects_list`	List projects (checked-out repos) in the active organization
`projects_create`	Register a project on a host: clone a Git URL or import an existing local repo

Hosts

Tool	Description
`hosts_list`	List the hosts (registered machines) you have access to

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, .amp/settings.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 workspace for the auth feature on my MacBook"
"Schedule a daily automation that triages new Linear issues at 9am"
"Pause the nightly cleanup automation"
"Show me the last 10 runs of my Linear triage automation"

MCP Server

Overview

Capabilities

Setup

CLI Options

Manual Configuration

Authentication

API Key Authentication

Available Tools

Tasks

Workspaces

Automations

Projects

Hosts

Chat Integration

Example Usage

On this page