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, 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 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.

Run an Export

Tool: run_export

Use this tool to create an on-demand export. The MCP client can resolve a dashboard, visualization, or widget first, and then call run_export with the required export mode and identifiers.

Example requests:

• Export the Executive KPI dashboard to PDF.
• Give me the Revenue table for Q4 as Excel.
• Create a PPTX of the Quarterly Review dashboard.
• Capture a PNG of the Pipeline Funnel widget at 1920 x 1080.

The response includes a download URL and metadata for the exported file.

Use Generated API Tools

When generated API tools are enabled and your MCP client supports tool search, you can ask for supported workspace-scoped API operations directly.

For example, an agent can search for the right tool and use it to read or create supported workspace metadata without making a separate REST API call.

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. Generated API tools enforce the same permissions as the underlying GoodData API.
• 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.
• Tool Search: Tool-search-capable clients can discover additional tools on demand. Clients without tool search see only the always-on core tools.
• Generated API Tools: Generated tools are workspace-scoped and include GET operations and selected create operations only.
• Exports: On-demand exports may take time to complete. Large files are returned through download URLs rather than embedded in the tool response.

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.

Tool Search Is Not Available:

• Check whether your MCP client supports dynamic tool discovery.
• If the client does not support tool search, only the always-on core tools are listed.

Generated API Tool Is Missing:

• Check that generated API tools are enabled for your environment.
• Some operations are intentionally not exposed, including PUT, PATCH, DELETE, action endpoints, organization-scoped endpoints, and non-allowlisted create operations.
• Use tool search to find generated tools instead of relying only on the initial tool list.

Export Fails:

• Verify that you have the required export permission for the requested export type.
• Check that the referenced dashboard, visualization, widget, or execution result exists and is accessible.
• For large exports, wait for the export to complete and use the returned download URL.

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.

Some capabilities, such as generated API tools, require MCP clients that support tool search and dynamic tool discovery. Clients without tool search can still use the always-on core tools.

Supported client examples:

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