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.
• Once connected, you can use natural language to trigger GoodData tools, such as listing metrics, creating alerts, creating metrics, or searching workspace metadata.

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 28 tools organized into the following categories.

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.

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.

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 currently supports authentication with a GoodData API token. Pass the token as a Bearer token in your MCP client configuration:

Authorization: Bearer <your-api-token>

Example Configurations

Claude Desktop

Claude Desktop supports stdio MCP servers natively. To connect to the GoodData streamable HTTP endpoint, use the mcp-remote bridge through npx.

Configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "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>"
      }
    }
  }
}

Restart Claude Desktop after saving the configuration. The Bearer token is passed through the env block instead of directly as a CLI argument to avoid cross-platform issues with spaces.

Claude Code

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

The --transport option must come before the server name. Use http as the transport value, not streamable-http.

Cursor

Configuration file: ~/.cursor/mcp.json for global configuration, or .cursor/mcp.json for a project. You can also configure the server from Cursor Settings > MCP.

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

Cursor auto-detects the transport from the URL. You do not need to add a type field.

VS Code with GitHub Copilot

Configuration file: .vscode/mcp.json, or use MCP: Open User Configuration from the Command Palette.

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

The root key is servers, not mcpServers. The type is http, not streamable-http. VS Code tries Streamable HTTP first and falls back to SSE. This setup requires the GitHub Copilot extension with MCP support enabled.

Usage Examples

Browse Metrics

Tool: list_workspace_metrics

Optional filters:

• title=like=*revenue* - Find metrics with “revenue” in the title
• tags=in=('finance','kpi') - Filter by tags
• limit=10 - Limit results to 10 metrics

Get specific metric:

• list_workspace_metrics(entity_id="revenue_total") - Retrieve full metric details including MAQL definition

Create a Metric

Tool: create_metric

Use this tool to create a governed metric in the workspace. The metric becomes part of the semantic layer and can be reused by other GoodData capabilities.

Create Alerts

Tool: create_metric_alert

Comparison Alert Example:

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 * * *"

Range Alert Example:

operator: "BETWEEN"
from_value: 100000
to_value: 1000000

Relative Alert Example:

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"

Update Alerts

Tool: update_metric_alert

Examples:

• Update threshold: threshold=2000000
• Convert to range alert: operator="BETWEEN", from_value=100000, to_value=500000
• Change to relative alert: operator="INCREASES_BY", compare_metric_id="revenue_last_month", threshold=0.15
• Update schedule: cron="0 30 14 * * 1-5", timezone="UTC"

Update Alert State

Tool: update_alert_state

Use this tool to pause or resume alerts.

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

Create Scheduled Exports

Tool: create_scheduled_export

Use this tool to create recurring exports of dashboards or visualizations.

AI Search and Chat

AI Search:

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

AI Chat:

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

Multi-turn conversation:

# 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
)

Label Elements (AFM)

Tool: compute_label_elements

Examples:

• Basic lookup: label_id="attr.customer.name"
• Pattern search: pattern_filter="Premium%"
• Exact filter: exact_filter=["North America", "Europe"]
• Exclusion: exact_filter=["Archived", "Deleted"], complement_filter=True
• Pagination: offset=200, limit=100

Scan Datasource and Generate LDM

Step 1: Scan datasource

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

Step 2: Generate LDM

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

Register Upload Notification

Tool: register_upload_notification

Use this tool after new data is uploaded for a datasource to invalidate related cache. This operation is organization-scoped and requires the MANAGE permission.

Security and Permissions

• Authentication: Bearer token required for all operations.
• Workspace Isolation: All operations are scoped to the authenticated user’s workspace context.
• Permission Enforcement: Tools respect user permissions and only return objects you can access.
• Organization-scoped Operations: Datasource operations may require elevated permissions.
• Alert Recipients: Must match the notification channel’s allowedRecipients configuration.

Limits and Behavior

• Stateless HTTP Streaming: Optimized for MCP clients with stateless operation.
• Pagination: List tools support limit parameter (recommended: 10-50 for quick browsing).
• RSQL Filtering: Advanced filtering using RSQL syntax on list operations.
• Cron Format: "second minute hour day month weekday" (e.g., "0 0 8 * * *" = daily at 8 AM).
• Label Elements: Default limit 100, maximum 10000.
• Error Handling: Structured error responses with field-level validation messages.

Troubleshooting

401/403 Errors:

• Verify your API token is valid and has access to the workspace.
• Check that you have the required permissions for organization-scoped operations (datasources).

404 Errors:

• Object may not exist or you may lack permission to view it.
• Verify workspace ID is correct in the endpoint URL.

Invalid RSQL Filter:

• Check RSQL syntax (e.g., title=like=*revenue*).
• Verify field names match available metadata fields.

Alert Creation Failures:

• Comparison alerts require threshold parameter.
• Range alerts require both from_value and to_value.
• Relative alerts require compare_metric_id and threshold.
• Recipients must match notification channel’s allowedRecipients policy.

Label Elements Errors:

• limit must be > 0 and ≤ 10000.
• sort_order must be "ASC" or "DESC".

LDM Generation:

• Ensure PDM comes from successful scan_datasource operation.
• Can pass entire scan result or just the pdm field.

Compatibility

The GoodData MCP Server is compatible with MCP clients that support the required transport and protocol version.

Supported client examples:

• Claude Desktop, through mcp-remote
• Claude Code
• Cursor
• VS Code with GitHub Copilot
• MCP Inspector
• Custom MCP clients