Oryx Docs

MCP Integration

Superset MCP (Model Context Protocol) is an intermediary server and protocol that provides programmatic control over Apache Superset instances using artificial intelligence agents. In simpler terms, it serves as a "bridge" between AI systems (such as OpenAI, Claude, Windsurf) and the Superset data visualization platform.

General Process

  1. Issue a token to connect to the MCP server.
  2. Connect to the MCP server.

How to Issue an Access Token

Note: To issue a token, contact the corporate portal support.

  1. Go to the application administration section of the corporate portal.
  2. In the application list, click on the entry Superset.
  3. In the application form, select the Access Tokens tab, then click Issue manually.
  4. In the Issue Client Token form:
    • input field Name: enter the token name. For example, MCP.
    • selection field User: select the desired user, click on the selection field, then start entering the user's details.
    • Access Rights (set the necessary options; when setting all options, click Select All):

Note: When issuing an access token under the OpenID Connect (OIDC) protocol, scopes are specified — these are the "permissions" that the user grants the application to work with their data.

  • option openid (Enable OpenID Connect): activates the OIDC protocol — the basis for user authentication. This option is mandatory.
  • option profile (Information about your profile): grants access to read user profile data.
  • option email (Information about your email address): grants access to read the user's email.
  • date selection field Expires: click on the field and set the token expiration date. Confirm the date selection.
  • Click Submit.

Upon successful issuance of the token, the message Token successfully issued will appear in the Issue Client Token form, and the values of the corresponding tokens will be displayed in the Access Token and Refresh Token fields.

  1. Copy the values of the corresponding tokens and store them in a location inaccessible to third parties.
  2. Close the Issue Client Token form.

After closing the form, a new entry with information about the issued access token will appear in the access token list.

Warning: When issuing tokens and subsequently transferring them to the owner, ensure a secure method of transmission and storage of access tokens.

How to Connect an AI Client to the MCP Server

Configuration Methods. After starting the MCP server, it is necessary to configure the AI client to connect to it. The connection setup is done through configuration files and depends on the specific client (see the documentation for the required AI client). There are two main types of configuration:

  • through a global configuration file at the application level: for example, for Claude Desktop: claude_desktop_config.json;

Note: Provides global scope.

  • through a .mcp.json configuration file at the project level.

Note: Provides local scope.

Example configuration at the application level for Claude Desktop:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "superset": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://superset.gddev.ru/mcp",
        "--header",
        "Authorization: Bearer YOUR_TOKEN"
      ]
    }
  }
}
  • "mcpServers" — the root key of the configuration that contains the description of all connected MCP servers;
  • "superset" — a unique name (identifier) of the specific MCP server within the configuration;
  • "command" — the value contains the utility to invoke the execution of the package specified in "args", passing it command-line arguments;
  • "args" — an array of arguments passed to the command specified in "command":
    • "-y" — a flag to confirm actions without user prompt;
    • "mcp-remote@latest" — the name of the npm package that implements the client side of MCP for connecting to remote servers, specifying to use the latest available version;
    • "https://superset.gddev.ru/mcp" — the URL of the Apache Superset MCP server;
    • "--header" — a flag for passing HTTP headers in the request to the MCP server;
    • "Authorization: Bearer YOUR_TOKEN" — sends the authentication token to the server for access to the MCP server. Important: replace YOUR_TOKEN with the actual API token or JWT token issued for access to Superset.

Restart the AI client. The AI client gains access to Superset tools through MCP (e.g., creating dashboards, querying data, managing access, etc.).

Note: * If necessary, request the MCP server URL from the server administrator.

  • The configuration file may differ for specific AI clients.
  • Check the connection using the tools of the specific AI client.

Example configuration at the project level for Claude Code (CLI). Add a file with the .mcp.json extension to your project:

Note: The CLI tool runs in the project directory where the .mcp.json is present.

{
  "mcpServers": {
    "superset": {
      "type": "http",
      "url": "https://superset.gddev.ru/mcp",
      "headers": {
        "Authorization": "Bearer ${SUPERSET_MCP_TOKEN}"
      }
    }
  }
}
  • "mcpServers" — the root key of the configuration that contains the description of all MCP servers connected to the project;
  • "superset" — a unique identifier of the MCP server within the project;
  • "type": "http" — specifies the protocol for connecting to the MCP server;
  • "url": "https://superset.gddev.ru/mcp" — the URL of the MCP server;
  • "headers" — a block of HTTP headers that will be added to all requests to the MCP server;
  • "Authorization": "Bearer ${SUPERSET_MCP_TOKEN}" — the authorization header for accessing the MCP server. Format: Bearer «token».

Note: * If necessary, request the MCP server URL from the server administrator.

  • The configuration file may differ for specific AI clients.
  • Check the connection using the tools of the specific AI client.

Important Notes:

  • The access token (YOUR_TOKEN) is issued by the administrator. Do not share it with third parties.
  • Confirm the current server address with the administrator.
  • If authentication errors occur, check the correctness of the token and URL.

On this page

General ProcessHow to Issue an Access TokenHow to Connect an AI Client to the MCP Server