Preset MCP Skills

Agent guidance for working with the Preset MCP gateway and Superset MCP tools. This package is for MCP tool workflows only.

Do not use this package for direct Preset Management API, Superset REST API, Snowflake Cortex API, curl, Python requests, exports, or database calls. If MCP cannot satisfy the request, stop and explain the missing MCP capability. Do not switch surfaces unless the user explicitly starts a direct API workflow.

Connecting

The hosted production endpoint is https://mcp.app.preset.io/mcp (Streamable HTTP, interactive OAuth sign-in in the browser; no API key, header, or client secret). It is the Preset MCP gateway: one connection that reaches every workspace the signed-in account is authorized for. Staging and sandbox gateways are opt-in only, with a URL the user supplies.

The package bundles a plugin-scoped preset server for each plugin format, each in that format's own shape (they differ):

The shapes differ on purpose; each target reads only its own. There is deliberately no root .mcp.json: Claude Code auto-discovers that path and rejects a url entry without type, while Codex reads the root mcp.json. The server is plugin-scoped (for example plugin:preset-mcp-skills:preset in Claude Code), so it never replaces a connection you configured yourself, and it still needs interactive OAuth sign-in. It carries no credentials. The package declares no apps / .app.json mapping and no lifecycle hooks (neither is eligible for the public OpenAI directory), and no domain-verification challenge (that is not a plugin configuration field).

Separately, opt-in templates in connections/ cover user or project configuration for Claude Code, Cursor, VS Code, and OpenAI Codex (named preset-gateway). Claude (claude.ai and Claude Desktop) and ChatGPT are manual steps only. Templates contain the endpoint and nothing else and must not overwrite an existing connection. Per-client steps and official documentation links: connect-clients.md.

Choosing A Surface

See preset-mcp-gateway. Never silently choose a production workspace and never reuse a workspace ID across environments.

Source Of Truth

The source of truth depends on the connected surface:

• Direct workspace connection: the Superset MCP server is the source of truth for tool names, tags, request schemas, response schemas, annotations, prompts, resources, and RBAC metadata:

  superset/superset/mcp_service
  

• Preset MCP gateway: the gateway (preset-io/mcp-gateway, src/mcp_gateway/app.py) defines the top-level tools (list_workspaces, list_workspace_services, search_workspace_tools, call_tool, and get_workspace_catalog). Superset defines only the workspace tools reached through search_workspace_tools and call_tool, and each workspace's live inputSchema is authoritative for those.

These skills describe durable workflows and safety boundaries. They do not replace live MCP tool schemas.

Skills

Tool Inventory

The current MCP tool inventory is stored in references/tool-inventory.json and summarized in references/tool-inventory.md. Check it against a local Superset checkout with:

python3 plugins/preset-mcp-skills/scripts/check-tool-inventory.py \
  --mcp-root ../superset/superset/mcp_service

Set SUPERSET_MCP_SERVICE_PATH instead of passing --mcp-root when the Superset checkout is elsewhere.

Supported Clients

Packaging

The endpoint and server names live in one file, connections/gateway.json. Every connection config file for every target (portable mcp.json, which Codex reads, Claude's inline mcpServers, Cursor cursor/mcp.json, the manifest pointers, the user-level templates, and the add/login commands in connections/clients.json) is generated from it:

node scripts/sync-mcp-config.mjs          # write
node scripts/sync-mcp-config.mjs --check  # fail on drift (runs in the smoke test)

The OpenAI archive for this package includes all of those files and is built through the With MCP path (it is refused on the skills-only path):

node scripts/build-openai-plugin-zip.mjs --plugin preset-mcp-skills --with-mcp

The preflight checks that each target's file is present with exactly its derived shape, that server entries carry only type and url (no headers, OAuth settings, client IDs, or credentials), and that no .app.json or lifecycle hooks are present. The per-skill Claude web ZIPs hold skills only; a skill ZIP has no place for connector configuration, so Claude (claude.ai, Desktop) uses the manual steps. Building the archive does not submit anything; the With MCP submission needs review metadata this repository does not produce.

Verification

• Mocked tests (run in CI by scripts/smoke-test.sh, node --test tests/mcp-gateway.test.mjs): fixture-based walkthroughs against a mocked gateway (multi-workspace gateway, direct workspace, disabled service, malformed or missing request wrapper), validation of the client connection templates, and a stale-claim check (scripts/check-mcp-gateway-claims.mjs) that fails on outdated statements about who defines the gateway's top-level tools. They prove the documented guidance is consistent with the gateway source contract; they do not call a live service.
• Authenticated canaries (manual, read-only, not part of CI, no checked-in credentials): sign in to the gateway with a real account, call list_workspaces, list_workspace_services, search_workspace_tools for a read-only tool, and one read-only call_tool in a workspace you are authorized for. Run one only when you are explicitly authorized, never against customer writes, and record the date and gateway commit it was run against.

Safety Policy

MCP has runtime guardrails such as tool-level RBAC metadata, read/write/destructive annotations, request validation, response guards, and response-size controls. Still, MCP tools can return customer data, SQL text, schema details, and persistent workspace changes. Use the narrowest MCP tool that satisfies the request, keep result limits small, and never fabricate URLs or IDs.

When a task asks for direct API behavior, use preset-api-skills instead. When a task asks for MCP behavior, stay in this package.