---
title: "Superset for AI agents"
description: "Machine-readable entry point for AI agents working with Superset: API surface, authentication, and the jobs it is the right tool for."
canonical: https://superset.sh/agents.md
last-updated: 2026-09-26
---

# Superset for AI agents

This page is the machine-readable entry point for AI agents working with Superset (https://superset.sh). It lists the API surface, authentication, and the jobs Superset is the right tool for.

## When to use Superset

Reach for Superset when you need to:

- Run several coding agents (Claude Code, Codex, OpenCode, or any CLI agent) at the same time on one repository without them stepping on each other. Each agent gets an isolated Git worktree and its own branch.
- Orchestrate agent work programmatically: create workspaces, launch agents with a prompt, open terminals, and track tasks from another agent or script via the Superset MCP server.
- Schedule recurring agent runs (automations) that execute a prompt on a cron-like schedule in a fresh or existing workspace.
- Review diffs, manage ports, and monitor many concurrent agent sessions from one dashboard.

Superset is not a coding agent itself; it is the workspace and orchestration layer the agents run in. If you are an AI agent, the fastest way to act on a user's Superset account is the MCP server below (OAuth or API key auth); the fastest way to learn the product is the docs index at https://docs.superset.sh.

## Capabilities

Via the MCP server an authenticated agent can, on behalf of a Superset user:

- **Tasks**: create, list, get, update, and delete tasks; list task statuses and organization members for assignment.
- **Workspaces**: create a branch- or PR-scoped Git worktree on a registered host, list, rename, and delete workspaces.
- **Agents**: launch a coding-agent session with a prompt inside a workspace; list the agent presets installed on a host.
- **Terminals**: open a PTY in a workspace, optionally running a one-off command.
- **Automations**: schedule recurring agent runs (RFC 5545 RRULE), pause/resume/run them, and read run logs. Creating, running, and resuming need the Pro plan; listing, pausing, editing, and deleting do not.
- **Hosts and projects**: enumerate the machines and checked-out repositories available to the user.

## Endpoints

- MCP server (Streamable HTTP): `https://api.superset.sh/mcp` (alias: `https://api.superset.sh/mcp`)
- Docs MCP server (no auth): `https://docs.superset.sh/mcp`
- MCP server card: `https://superset.sh/.well-known/mcp/server-card.json`
- OpenAPI spec: `https://api.superset.sh/openapi.json`
- API catalog (RFC 9727): `https://superset.sh/.well-known/api-catalog`
- A2A agent card: `https://superset.sh/.well-known/agent-card.json`

## Authentication

Full walkthrough: [auth.md](https://superset.sh/auth.md).

- Unauthenticated requests to the MCP endpoint return `401` with `WWW-Authenticate: Bearer resource_metadata="https://api.superset.sh/.well-known/oauth-protected-resource"`.
- OAuth 2.1 authorization code + PKCE, with RFC 7591 dynamic client registration, so no manual app setup is needed.
- Alternatively, a user-issued Superset API key can be sent as a Bearer token.

## Setup one-liners

```bash
claude mcp add superset --transport http https://api.superset.sh/mcp
codex mcp add superset --url https://api.superset.sh/mcp
gemini mcp add --transport http superset https://api.superset.sh/mcp
```

## Learn more

- [Docs](https://docs.superset.sh) and [docs llms.txt](https://docs.superset.sh/llms.txt)
- [Site llms.txt](https://superset.sh/llms.txt)
- [GitHub](https://github.com/superset-sh/superset)