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, signed JWT, or Interactive SSO when enabled for your organization.
• 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 server’s built-in tools, the server can expose GoodData v1 metadata 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

Tool Search

When tool search is enabled, tools/list returns only these two tools:

• search_tools - Search for MCP tools using a natural-language query. Results are ranked using each tool’s name, description, and parameter descriptions.
• call_tool - Call a tool returned by search_tools by providing its name and arguments.

All other MCP tools remain available. They are not listed by tools/list, but a client that already knows an exact tool name can call that tool directly without using call_tool.

For integrations that discover capabilities dynamically, use search_tools to find a tool and call_tool to run it. Integrations that already call specific tools by name can continue doing so and should not treat tools/list as a complete catalog.

This behavior applies to both built-in tools and generated API tools.

Enable Tool Search and Generated API Tools

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.

Agents

• list_agents - List the organization’s AI agents. Requires the AI entitlement.

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

The MCP Server exposes supported GoodData v1 metadata API operations as generated MCP tools.

Every workspace-scoped GET endpoint in the metadata service is exposed as a read tool. Create tools are generated for these allowlisted workspace-scoped POST entities:

• metrics
• visualizationObjects
• analyticalDashboards
• dashboardPlugins
• filterContexts
• filterViews
• exportDefinitions
• attributeHierarchies
• customApplicationSettings
• memoryItems

Generated tools do not include:

• PUT, PATCH, or DELETE operations
• action endpoints
• organization-scoped or admin-scoped endpoints
• create operations outside the allowlist

This lets agents read and create supported workspace metadata through MCP without calling the REST API separately.

Generated tools grant no additional access. The backend authorizes each call using the same permissions as the underlying GoodData API.

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.

Key Driver Analysis

• run_key_driver_analysis - Analyze what drove a change in a metric.

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 available knowledge topics and their resource URIs.
• 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.

How Workspace Inheritance Affects MCP Tool Results

When an AI agent connects to a child workspace through the MCP Server, it can access the analytical objects available in that workspace, including inherited metrics, attributes, visualizations, and dashboards.

The agent can use list_workspace_metrics, list_workspace_attributes, list_workspace_visualizations, and list_workspace_dashboards to discover available objects. It can then use tools such as execute_visualization to work with those objects.

Example: Analyze Data in a Child Workspace

Suppose a parent workspace, sales, contains a revenue_by_region visualization. Its child workspace, sales_west, inherits the visualization and has a workspace data filter that limits the relevant data to the West region.

A user asks an AI agent connected to sales_west:

“Show me revenue by region.”

The agent can find the inherited visualization and execute it using the MCP tools. The result respects the child workspace’s data restrictions, so it may differ from the result of executing the same visualization in the parent workspace.

The user does not need to know which tools to call or whether the visualization is inherited.

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.

For a person using a supported MCP client directly, Interactive SSO allows browser-based sign-in with the organization’s identity provider. Requests run with that user’s permissions. See Interactive SSO.

Interactive SSO

With Interactive SSO, a supported MCP client can connect without a manually configured API token. GoodData acts as the OAuth 2.1 authorization server for the MCP client. The user signs in through the organization’s existing OpenID Connect identity provider, and GoodData then issues an access token to the MCP client. The identity provider does not communicate directly with the MCP client. The token represents the user’s GoodData access and is not limited to MCP operations.

Interactive SSO is disabled by default. For activation, consent, token expiry, and OAuth endpoints, see OAuth 2.1 for Interactive AI Clients.

To connect, configure the MCP endpoint without an Authorization header. For example:

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

For Claude Code, add the MCP server with:

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

On first use, your MCP client detects that authentication is required, opens the browser sign-in flow, and returns to the client after you sign in and complete any required consent. Subsequent tool calls use your GoodData permissions.

Build a Client with Interactive SSO

MCP clients that support interactive OAuth discover the required endpoints automatically. If you build your own client, use the discovery and registration endpoints described in OAuth Discovery and Endpoints.

API Token

API-token authentication continues to work. Pass the token as a bearer token in the MCP client configuration:

Authorization: Bearer <your-api-token>

Example Configurations

The examples below use API-token authentication. If your client supports Interactive SSO, configure only the MCP server URL as described in Interactive SSO and omit the Authorization header.

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

Generated API tools let agents 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: All operations require bearer authentication. Use a GoodData API token, signed JWT, or a token issued after Interactive SSO sign-in.
• 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 grant no additional access and 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: tools/list returns only search_tools and call_tool. All other tools remain callable by exact name.

• Generated API Tools: Generated tools are enabled by default, are workspace-scoped, and include metadata-service GET operations and allowlisted 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:

• If Interactive SSO is enabled and your client supports it, an HTTP 401 challenge can cause the client to open the browser sign-in flow. This is expected behavior.
• If you use an API token, verify that the token is valid and has access to the workspace.
• A 403 usually means the authenticated user does not have permission for the requested operation. Check the required workspace or organization permissions.

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.

Only search_tools and call_tool Are Listed:

• This is expected when tool search is enabled for your organization.
• Use search_tools to discover a tool and call_tool to run it.
• If your integration already knows the exact tool name, it can call that tool directly. Do not use tools/list as a complete catalog.

Generated API Tool Is Missing:

• Use search_tools to find generated tools instead of relying on the initial tool list.
• Some operations are intentionally not exposed, including PUT, PATCH, DELETE, action endpoints, organization-scoped endpoints, and non-allowlisted create operations.

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.

Supported client examples:

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