GoodData MCP Server

The Model Context Protocol (MCP) server exposes GoodData platform capabilities to external MCP clients. You can connect from your own MCP client, such as a chatbot, IDE assistant, or custom agent, and interact with GoodData using natural language.

AI is becoming part of everyday work, but connecting it safely to company data can be a challenge. Teams want their chatbots, IDE assistants, and custom agents to work with real data, while keeping access secure and consistent.

The GoodData MCP Server lets AI clients connect directly to governed analytics in GoodData, so they always reason with trusted metrics, metadata, and platform capabilities instead of raw or ad-hoc queries.

How It Works

• The MCP server exposes GoodData platform capabilities to AI agents and developer tools.
• It supports the MCP protocol with error handling, multi-workspace isolation, and authentication.
• You connect with your own MCP client using an API token or, for supported clients, by signing in through your organization’s identity provider.
• Once connected, you can use natural language to trigger GoodData tools, such as listing metrics, creating alerts, creating metrics, running exports, or searching workspace metadata.
• Tool search helps MCP clients discover additional tools on demand, so the server can expose a larger set of capabilities without listing every tool up front.
• In addition to the always-on core tools, the server can expose selected GoodData v1 API operations as MCP tools. These generated tools let agents use supported workspace-scoped API operations directly through MCP, without calling the REST API separately.

The latest supported MCP protocol version is 2025-11-25. Use MCP client libraries that support this protocol version.

Available Tools

The MCP Server provides a core set of always-on tools and additional tools that can be discovered through tool search. The exact number of available tools depends on the enabled MCP capabilities and the MCP client’s support for dynamic tool discovery.

Tool Search

When a large number of MCP tools is available, the server uses tool search to keep the initial tool list manageable. Tool-search-capable MCP clients can search for tools by intent and then call the matching tool.

This applies to both manually defined tools and generated API tools. Tool names and descriptions are used for search relevance.

Workspace Metadata

• get_workspace_info - Get workspace name, description, and organization information.
• list_workspace_metrics - List metrics with optional RSQL filtering and pagination. Supports optional entity_id for single-metric retrieval.
• list_workspace_attributes - List attributes with optional RSQL filtering and pagination. Supports optional entity_id for single-attribute retrieval.
• list_workspace_visualizations - List visualizations with optional RSQL filtering and pagination. Supports optional entity_id for single-visualization retrieval.
• list_workspace_dashboards - List dashboards with optional RSQL filtering and pagination. Supports optional entity_id for single-dashboard retrieval.

List operations:

• entity_id - Retrieve a single entity through the relevant list_* tool when supported.
• include - Request related entities in one call, such as facts, labels, datasets, or visualizations.
• limit - Optional pagination. Recommended values are 10-50 for quick browsing and 100+ for comprehensive lists.
• rsql_filter - Optional RSQL filtering, for example title=like=*revenue* or tags=in=('finance','kpi').

All list_* tools support the include parameter to fetch related entities in a single request. Examples of valid includes:

• Metrics: ["facts", "attributes"]
• Dashboards: ["visualizations"]
• Attributes: ["labels", "datasets"]

Example usage:

list_workspace_metrics(entity_id="revenue_total")
list_workspace_dashboards(entity_id="sales_dashboard", include=["visualizations"])
list_workspace_attributes(include=["labels", "datasets"])

Users

• list_users - Browse organization users.
• list_workspace_users - Browse users with access to the current workspace.

Datasources and Data Modeling

• list_datasources - List datasources with optional RSQL filtering and pagination. This is a read-only operation and supports optional datasource_id for single-datasource retrieval.
• test_datasource - Test datasource connectivity before scanning.
• scan_datasource - Discover Physical Data Model (PDM) from database schemas.
• generate_ldm - Generate Logical Data Model (LDM) from PDM.
• register_upload_notification - Invalidate cache after new data uploads.

Note: Datasource operations are organization-scoped and may require elevated permissions, such as MANAGE.

Analytics Authoring

• get_workspace_analytics - Retrieve complete analytics model from a workspace, including metrics, dashboards, visualizations, filter contexts, attribute hierarchies, export definitions, and dashboard plugins.
• create_metric - Create a new governed metric in the workspace.
• deploy_workspace_analytics - Deploy full analytics model to a workspace.

Generated GoodData v1 API Tools

When generated API tools are enabled, the MCP Server can expose selected GoodData v1 API operations as MCP tools.

Generated tools are workspace-scoped. They can include:

• read operations based on GET endpoints
• selected create operations based on allowlisted POST endpoints

Generated tools do not include:

• PUT, PATCH, or DELETE operations
• action endpoints
• organization-scoped or admin-scoped endpoints
• create operations that are not explicitly allowed

This lets agents perform supported metadata and authoring tasks through MCP, such as reading workspace objects or creating supported workspace objects, without calling the REST API directly.

Generated tools still enforce the same GoodData permissions as the underlying API. If a user does not have permission for an operation, the tool returns a permission error that the MCP client can show to the user.

Memory

• create_memory_item - Add persistent instruction or context to the AI system prompt for the workspace. Maximum length is 255 characters.

AI-Powered Search and Chat

• ai_search - Natural language search across workspace data with AI-generated insights.
• ai_chat - Conversational assistant with intelligent routing:
  • Semantic Search - Find existing dashboards, metrics, and visualizations.
  • Visualization Creation - Generate new visualizations from natural language.
  • General Questions - Get answers about analytics concepts and best practices.
  • Supports thread continuity for multi-turn conversations.

AFM Execution (Label Elements)

• compute_label_elements - Retrieve distinct label (attribute) values with:
  • Pattern filtering (SQL LIKE syntax: "Premium%")
  • Exact filtering (["USA", "Canada"])
  • Exclusion mode (complement_filter=True)
  • Pagination (default: 100, max: 10000)
  • Dependent filters and validation by metrics/attributes
• execute_visualization - Execute a saved visualization and return its computed result so MCP clients can use the data in downstream analysis or assistant workflows.

Automations and Alerts

• list_notification_channels - Discover available delivery channels (email, Slack, webhooks).
• list_automations - List all automations in the workspace.
• create_metric_alert - Create unified metric-based alerts supporting:
  • Comparison alerts: GREATER_THAN, LESS_THAN, EQUAL_TO, GREATER_THAN_OR_EQUAL_TO, LESS_THAN_OR_EQUAL_TO, NOT_EQUAL_TO
  • Range alerts: BETWEEN, NOT_BETWEEN
  • Relative alerts: INCREASES_BY, DECREASES_BY, CHANGES_BY (with DIFFERENCE or CHANGE arithmetic)
  • Schedule configuration (cron format, timezone)
  • Recipients (internal user IDs and/or external email addresses)
  • Metric formatting (titles and number formats for readable notifications)
• update_metric_alert - Update alert thresholds, operators, recipients, schedules, or convert alert type.
• update_alert_state - Pause or resume alerts by setting the target state. Use state="pause" or state="unpause". The tool accepts either a single automation ID or a list of automation IDs.
• create_scheduled_export - Create a recurring export of a dashboard or visualization.

Example of Use

1. You ask the assistant: “Alert me if Total Revenue drops below 90K.”
2. The assistant analyzes your request and sets parameters:
   • metric = Total Revenue
   • operator = LESS_THAN
   • threshold = 90000
   • schedule = every morning at 8am
   • delivery = your default method
3. You get confirmation: “Alert created: will check daily and notify you when Total Revenue < 90K.”

Important Recipient Rules:

Recipient types must match the notification channel’s allowedRecipients setting:

• CREATOR: Only the current user can be an internal recipient.
• INTERNAL: Only internal_recipients (user IDs) are allowed.
• EXTERNAL: Both internal user IDs and external email addresses are allowed.

Export Tools

• run_export - Run an on-demand export and return a download URL and file metadata.

The run_export tool can run supported export modes, such as:

• dashboard PDF export
• tabular XLSX export
• raw execution export
• dashboard slide deck export in PPTX format
• widget image export, such as PNG snapshots

The tool returns structured metadata where available, such as MIME type, file size, dashboard or visualization links, row and column counts for tabular exports, and width and height for image exports. Large files are returned through download URLs instead of being embedded in the response. Small image assets may be returned inline when supported by the client.

Exports are asynchronous. The tool reports progress while the export is being prepared and returns the file information after the export is complete. Some export types, such as slide decks, may take longer than simple image or tabular exports.

The tool uses existing GoodData export permissions. If the user lacks the required permission, the tool returns an error with information about what needs to be fixed before retrying.

Knowledge Base Tools

The GoodData MCP Server provides tools for accessing platform documentation and analytics knowledge. These allow MCP clients to retrieve structured guidance on MAQL, dashboards, datasets, visualizations, and the Logical Data Model.

• get_maql_guide - Returns MAQL syntax rules, function explanations, and examples. Clients can use this to learn metric syntax that is not part of general LLM training data.
• list_knowledge_topics - Lists all available knowledge topics: gooddata, maql, dashboards, visualizations, datasets, and ldm-schema.
• get_knowledge_topic - Retrieves the full content of a specific knowledge topic.

Knowledge Resources

All knowledge topics exposed through the Knowledge Tools are also available as MCP Resources for clients that support resource querying. This allows AI agents to load documentation directly as structured content and use it to understand GoodData concepts.

Available Knowledge Resource URIs:

Each resource contains structured documentation that AI assistants can load, summarize, and reason about, enabling more accurate results when working with analytics or metadata definitions.

Connect

Endpoint

Use this endpoint to connect:

https://<your-gooddata-host>/api/v1/actions/workspaces/<workspaceId>/ai/mcp

Replace <workspaceId> with the workspace ID you want to work in.

Authentication

The MCP Server supports multiple authentication approaches. Choose the method based on how the MCP client runs:

For server-side integrations, prefer a signed JWT when the integration needs to act as individual users. Interactive SSO is intended for a person using an MCP client directly.

Interactive SSO

With interactive SSO, you do not create or paste a GoodData API token into the MCP client configuration. A compatible client discovers GoodData authentication automatically, opens your organization’s normal sign-in page in a browser, and obtains access after you sign in. Tool calls then run with your existing GoodData permissions. The token represents the same user access available through the GoodData API; it is not limited only to MCP operations.

{
  "mcpServers": {
    "GoodData": {
      "type": "http",
      "url": "https://<your-gooddata-host>/api/v1/actions/workspaces/<workspaceId>/ai/mcp"
    }
  }
}

claude mcp add --transport http GoodData \
  "https://<your-gooddata-host>/api/v1/actions/workspaces/<workspaceId>/ai/mcp"

POST /oauth2/revoke

Authorization: Bearer <your-api-token>

{
  "mcpServers": {
    "GoodData": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://<your-gooddata-host>/api/v1/actions/workspaces/<workspaceId>/ai/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <your-api-token>"
      }
    }
  }
}

claude mcp add --transport http GoodData \
  "https://<your-gooddata-host>/api/v1/actions/workspaces/<workspaceId>/ai/mcp" \
  --header "Authorization: Bearer <your-api-token>"

{
  "mcpServers": {
    "GoodData": {
      "url": "https://<your-gooddata-host>/api/v1/actions/workspaces/<workspaceId>/ai/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-token>"
      }
    }
  }
}

{
  "servers": {
    "GoodData": {
      "type": "http",
      "url": "https://<your-gooddata-host>/api/v1/actions/workspaces/<workspaceId>/ai/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-token>"
      }
    }
  }
}

automation_id: "revenue-milestone"
metric_id: "revenue_total"
operator: "LESS_THAN"
threshold: 90000
metric_format: "$#,##0"
metric_title: "Total Revenue"
notification_channel_id: "email-channel-id"
internal_recipients: ["user-id-123"]
cron: "0 0 8 * * *"

operator: "BETWEEN"
from_value: 100000
to_value: 1000000

operator: "INCREASES_BY"
compare_metric_id: "revenue_last_month"
threshold: 0.10
arithmetic_operator: "CHANGE"
compare_metric_format: "$#,##0"
compare_metric_title: "Last Month Revenue"

automation_id: "revenue-milestone"
state: "pause"

ai_search(question="What were the total sales last quarter?")

ai_chat(question="Give me bar chart slicing revenue by country")

# First request
result1 = ai_chat(question="Give me revenue by country")
thread_id = result1.thread_id_suffix

# Follow-up maintains context
result2 = ai_chat(
    question="And now filter to USA only",
    thread_id_suffix=thread_id
)

scan_datasource(
    datasource_id="my_db",
    schemas=["public"],
    scan_tables=True,
    scan_views=True
)

generate_ldm(
    datasource_id="my_db",
    pdm=scan_result  # Pass entire scan result or scan_result["pdm"]
)