MCP Server

The Superset MCP server lives at https://api.superset.sh/mcp. The versioned URL (/api/v2/agent/mcp) keeps working for existing configurations; the legacy v1 server (/api/agent/mcp) has been removed and returns 410 Gone.

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, list statuses
Workspaces	list (per host), create on a host, update, delete
Agents	list agents on a host, launch an agent session in a workspace
Terminals	create in a workspace, list, send input, read screen, close
Automations	list, get metadata, get/set prompt body, create, update metadata, pause, resume, run on demand, list runs, delete
Projects	list projects on a host
Hosts	list hosts (registered machines) you have access to
Organization	list members

Setup

CLI Options

terminal

claude mcp add superset --transport http https://api.superset.sh/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/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/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`	Soft-delete a task by UUID
`tasks_statuses_list`	List the organization's task statuses (for `tasks_create`/`tasks_update` statusId)

Workspaces

Tool	Description
`workspaces_list`	List workspaces on a host (get the hostId from `hosts_list`)
`workspaces_create`	Create a workspace on a host (branch-scoped git worktree)
`workspaces_update`	Update fields on a workspace on its host
`workspaces_delete`	Delete a workspace by UUID on its host

Agents

Tool	Description
`agents_list`	List agents configured on a host
`agents_create`	Create (launch) an agent session in an existing workspace

Terminals

Tool	Description
`terminals_create`	Create a terminal session in a workspace, optionally running a command
`terminals_list`	List terminal sessions in a workspace
`terminals_send`	Write text into a running terminal (presses Enter by default)
`terminals_read`	Read the terminal screen as plain text (current screen plus recent scrollback)
`terminals_close`	Close a terminal session and kill its process

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) on a host (get the hostId from `hosts_list`)

Hosts

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

Organization

Tool	Description
`organization_members_list`	List members of the active organization

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, .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

On this page