tomikng/superset/plugins

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

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, from the PLUGIN column of superset plugins list. A connection id is not accepted: credentials live on the connector a plugin names, and one connector can back several plugins, so an id no longer says which plugin was meant.

Arguments are the last positional, not an option, and - reads them from stdin.

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

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

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