MCP Service in Apache Superset#

Overview#

The Model Context Protocol (MCP) service (superset/mcp_service/) enables AI assistants (e.g., Claude) to programmatically interact with Apache Superset — creating dashboards, generating charts, executing SQL, and querying metadata. It is built on FastMCP and runs as a standalone sidecar process alongside the main Superset webserver. 1

The service is optional: fastmcp is listed only in requirements/development.in and as a pyproject.toml extra, so Superset runs normally without it and no database migrations are required. 2

Architecture#

The service lives entirely under superset/mcp_service/ and follows a domain-driven layout:

superset/mcp_service/
├── __main__.py # stdio-mode entry point
├── app.py # FastMCP factory (registers all tools on import)
├── server.py # HTTP/streamable-http server runner
├── mcp_config.py # Centralized config, reads from Flask app.config
├── flask_singleton.py # Module-level Flask app singleton
├── auth.py # JWT user resolution
├── middleware.py # Middleware stack (logging, errors, permissions, rate limit)
├── mcp_core.py # Reusable core classes
├── chart/ # 8 chart tools + validation pipeline + prompts + resources
├── dashboard/ # 5 dashboard tools
├── dataset/ # 3 dataset tools
├── sql_lab/ # 2 SQL Lab tools
├── explore/ # 1 explore tool
├── system/ # 2 system tools + prompts + resources
├── screenshot/ # Pooled Selenium WebDriver for chart previews
└── utils/ # cache, error builder, permissions, retry, URL utils

2

Key architectural patterns:

• All tools register via @mcp.tool / @mcp.prompt / @mcp.resource decorators; app.py triggers registration by importing each domain module. 2
• ModelListCore, ModelGetInfoCore, and ModelGetAvailableFiltersCore in mcp_core.py provide generic, reusable list/get/filter logic shared across all domains. 2
• A 5-layer validation pipeline guards generate_chart: schema (Pydantic) → business logic → dataset compatibility → Superset compatibility → runtime (cardinality, type suggestion). 2
• flask_singleton.py holds a module-level Flask app instance so MCP tools can invoke Superset's SQLAlchemy models and FAB security manager without a running webserver. 1

Middleware stack (enforced on every tool call via mcp_auth_hook): 2

1. LoggingMiddleware — audit logs via Superset's event logger
2. GlobalErrorHandlerMiddleware — normalizes errors to LLM-friendly messages
3. FieldPermissionsMiddleware — filters response fields by JWT scopes (dashboard: published/certified/favorite; chart: certified/favorite; dataset: schema/table_name)
4. RateLimitMiddleware — in-memory for dev, Redis for production
5. PrivateToolMiddleware — blocks tools tagged private

Tools, Prompts, and Resources#

21 tools across 6 domains 2:

2 prompts: superset_quickstart (onboarding), create_chart_guided (step-by-step chart wizard). 2

2 resources: superset://chart/templates (chart config patterns), superset://instance/metadata (capabilities and feature flags). 2

CLI & Running the Service#

The CLI entry point is superset/cli/mcp.py, registered as superset mcp run. 1

# HTTP mode (streamable-http transport), default port 5008
superset mcp run --host 0.0.0.0 --port 5008 --debug

# stdio mode (for Claude Desktop / local MCP clients)
python -m superset.mcp_service

Transport is selected via the FASTMCP_TRANSPORT environment variable (stdio or streamable-http). In stdio mode, __main__.py suppresses Flask initialization output to keep the MCP protocol stream clean. 1

Claude Desktop config (claude_desktop_config.json): 2

{
  "mcpServers": {
    "superset": {
      "command": "python",
      "args": ["-m", "superset.mcp_service"],
      "env": { "SUPERSET_CONFIG_PATH": "/path/to/superset_config.py" }
    }
  }
}

Configuration#

All MCP settings are defined in superset/mcp_service/mcp_config.py and overridable via superset_config.py. Flask's app.config is checked first, so user overrides always take precedence. 1

Authentication & Known Limitations#

Design intent: auth.py extracts the calling user from a JWT Bearer token and sets g.user for the Flask context. The mcp_auth_hook decorator wraps every tool to enforce this. 2

Current limitation (as of 6.1.0): MCP routes run under a FastMCP ASGI sub-app mounted on Flask. Flask's @before_request JWT middleware only fires for routes in Flask's own URL map, so /mcp/* requests bypass it entirely — g.user is never populated from the token. 3

Workaround: Set MCP_DEV_USERNAME=<username> in superset_config.py. All tool calls execute as that single delegated account. Per-request access-token authentication is planned for a future release. 3

⚠️ MCP_DEV_USERNAME collapses row-level security, dataset permissions, and audit trails to a single principal. Use a dedicated FAB role with minimum necessary grants.

Patching auth.py and mcp_config.py from the master branch is a documented workaround for Keycloak/SSO setups on 6.1.0. 3

Deployment#

Standalone process: Run superset mcp run --host 0.0.0.0 --port 5008 in a separate container or process. The /health HTTP endpoint works for liveness and readiness probes. 4

Kubernetes/Helm: Native Helm chart support is a community feature request (not yet merged). The proposed supersetMcp block mirrors the existing supersetWebsockets and supersetCeleryFlower patterns. 4

DevContainer: .devcontainer/with-mcp/devcontainer.json extends the base devcontainer with fastmcp, Selenium, and Chrome for local development including screenshot generation. 2

Key Source Files#

Open Issues & Future Work#

• Per-request JWT auth: Not yet in 6.1.0; requires ASGI auth middleware on the FastMCP mount or a Flask→ASGI bridge. 3
• Granular caching controls: MCP_CACHE_CONFIG currently exposes only TTL and excluded_tools. Per-operation enabled/included_tools/max_item_size controls are tracked in Discussion #42198. 5
• Helm chart support: First-class Kubernetes deployment templates tracked in Discussion #41441. 4