/plugins

name: plugins
description: Install Superset plugins, connect the accounts they need, and call their MCP tools through the credential proxy. Use when the user wants a plugin installed, removed, enabled, or connected, asks what tools a plugin exposes, wants to call one, adds a marketplace, or asks why a plugin's tools are not available.
argument-hint: what you want to install, connect, or call
allowed-tools: Bash(superset plugins:*) Bash(superset mcp:*) Bash(superset skills:*)

Plugins and their tools

A plugin brings two things: **skills**, which land in the directories agents read, and **MCP tools**, which are called through Superset's proxy. Install state lives on the account, so a plugin installed here is installed everywhere you sign in. The credential does not. It stays server-side, and no token is ever written to this machine.

1. See what is there

superset plugins list                  # installed, with status per plugin
superset plugins list --available      # everything the marketplace offers
superset skills list                   # skills on this machine, and their paths

The `status` column is the thing to read. `needs connection` means the skills are installed but no account is authorized, so the tools will fail. That is a connect step, not a bug.

2. Install

superset plugins install linear
superset plugins install linear --update      # move to the marketplace's current version
superset plugins install linear@superset      # when two marketplaces carry the same name

Install records the plugin on the account and materializes its skills locally. It prints whether a connection is still needed.

3. Connect an account

Two shapes, and the plugin's manifest decides which:

superset plugins connect linear                       # oauth2: prints a URL to open
superset plugins connect sentry --inputs '{"api_key":"..."}'
echo '{"api_key":"..."}' | superset plugins connect sentry --inputs -

Prefer stdin for a real credential: an argument is visible in `ps` and in shell history. OAuth cannot finish headlessly: hand the URL to the user, then confirm with `superset plugins connections --plugin linear`.

If a plugin offers more than one method, the command says so and lists them. Ask the user which they want rather than picking.

4. Call its tools

Address a plugin by name. When one name has several connected accounts, pass the connection id from the `PLUGIN ID` column of `superset plugins list` instead; there is no default account, so pick one deliberately.

superset mcp tools linear
superset mcp call-tool linear list_issues
superset mcp call-tool linear create_issue '{"team":"ENG","title":"Export 500s"}'
echo '{"team":"ENG","title":"..."}' | superset mcp call-tool linear create_issue -
superset mcp call-tool linear create_issue --connection <id> '{"team":"ENG","title":"..."}'

List the tools before calling one. Names and argument schemas come from the plugin's server, not from anything in this repo, and they change between versions. The `integrations` skill covers this end in full: reading a tool's arguments, choosing an account, parsing the result.

The call goes out from Superset's API, which attaches the credential. That is why this works with no token on the machine, and why a network-restricted sandbox can still reach a plugin's tools.

Reading a failure

| What you see | What it means | | --- | --- | | `needs connection` in `plugins list` | Installed, not authorized. Run `plugins connect`. | | 401/403 from a tool call | The stored credential was revoked or expired. Reconnect. | | `is not installed` | Installed on the account but not resolvable here; run `plugins install --update`. | | More than one marketplace named | Two installs share the name. Re-run with `name@marketplace`. |

5. Turn things off

superset plugins uninstall linear     # uninstall, and reap the skills it provisioned
superset plugins disable linear       # keep the install, stop provisioning its skills
superset plugins marketplace list
superset plugins marketplace add owner/repo      # add a third-party marketplace
superset plugins marketplace remove <name>

`uninstall` reaps only what the plugin provisioned; hand-written skills in the same directory are left alone. It removes the plugin locally even when the account call fails, and says so. Read that message: the stored credential is revoked as part of the account removal, so an unconfirmed removal means the skills are gone from this machine while the connection lives on. Check with `superset plugins connections --plugin <name>` and run `uninstall` again.

Anti-patterns

• Calling a tool without listing tools first. You are guessing at a name and a schema that

the plugin owns.

• Passing a secret as a command argument when the command accepts stdin.
• Treating `superset plugins sync` as a fix for a missing connection. Sync converges skills

on this machine; it has nothing to do with credentials.

• Installing a plugin to "see what it does". Install writes to the user's account and every

machine they use. Ask first.