Integrations

Calling an integration's tools

An integration is an installed plugin with a connected account. Its tools do not run here. superset mcp hands the call to Superset's API, which attaches the stored credential and forwards it to the plugin's MCP server. No token is ever written to this machine, which is also why a sandbox with no route to Linear can still file a Linear issue.

Installing, connecting, and marketplaces belong to the plugins skill. This one starts once something is connected, and it is two steps: list the tools, then call one.

1. Find the integration

superset plugins list                     # one row per connected account, one row if none yet
superset plugins connections --plugin linear

Read the STATUS column. connected: <account> is callable. needs connection means the skills are installed but no account is authorized, so its tools will fail until someone connects one; that is a connect step, not a bug. PLUGIN ID holds the connection id, and it is empty on a row with no connection yet. A plugin with two connected accounts has two rows and two ids.

2. List the tools before calling one

superset mcp tools linear
superset mcp tools --connection <id>              # when the name has several accounts
superset mcp tools linear | jq -r '.[].tool'      # names only; descriptions run long

Names and descriptions come from the plugin's own server, not from anything in this repo, and they change between plugin versions. Never call a tool you have not listed.

The listing gives a name and a description, but no input schema. The description is where the plugin documents its arguments, so read the full description of the tool you are about to call rather than the filtered name list. If the shape is still ambiguous, a wrong call comes back as a tool error naming the offending field; correct it from there.

3. Call it

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":"..."}'

The plugin name is the first positional and the tool name the second, always. --connection picks the account; it does not stand in for the plugin positional. Arguments are the third positional, default {}, and - reads them from stdin. Use stdin for anything secret, since an argument is visible in ps and in shell history.

What comes back is the MCP result verbatim: a content array whose text parts are usually themselves JSON strings.

superset mcp call-tool linear list_issues | jq -r '.content[0].text' | jq

When another skill expects tools you do not have

A plugin ships its own skills, and they are written against native MCP tools: the Linear, GitHub, and Sentry skills declare allowed-tools: mcp__linear__* and reach for tools by that name. Those tools exist only where the plugin's MCP server was written into this agent's config, which installing through the CLI does not do, and which today happens for Claude Code and Codex only. On every other agent the tool list will not have them.

That is this skill's job. When the tools a plugin's skill assumes are missing, do not stop and do not tell the user the integration is unavailable. The same operations sit on the connected account, one command away:

superset mcp tools linear                       # what the account can actually do
superset mcp call-tool linear create_issue '{"team":"ENG","title":"..."}'

Keep following the skill you were reading, since its judgment about what makes a good issue or a good triage still applies. Only the transport changes.

Reading a failure

Anti-patterns

• Calling a tool without listing tools first. You are guessing at a name and a schema the plugin owns.
• --plugin-id. Deprecated alias for --connection.
• Passing a credential as a command argument when the command reads stdin.
• Picking one of several connected accounts yourself. Which account acts is the user's call.
• Reconnecting on any 403. Half of them are a permissions problem on the account you already have.
• Reaching for superset plugins sync when a call fails on authorization. Sync converges skills on this machine; it has nothing to do with credentials.
• Installing or connecting a plugin to see what it offers. That writes to the user's account and reaches every machine they sign in on, so ask first and use the plugins skill.