--- title: "Grafana Cloud MCP server | Grafana Cloud documentation" description: "Connect external AI agents like Cursor, Claude Desktop, and Windsurf to your Grafana Cloud data using the Grafana Cloud MCP server." --- # Grafana Cloud MCP server > Note > > Grafana Cloud MCP server is currently in [public preview](/docs/release-life-cycle/). Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available. The Grafana Cloud MCP server is a remotely hosted Model Context Protocol (MCP) server that lets external AI agents connect directly to your Grafana Cloud data. MCP-compatible clients, for example, Cursor, Claude Desktop, Windsurf, and Goose, can query metrics, logs, and other observability data from your Grafana environment without any local installation. Unlike the [open source Grafana MCP server](https://github.com/grafana/mcp-grafana), which runs locally and requires manual service account token configuration, the Grafana Cloud MCP server is fully hosted and uses OAuth 2.1 authorization. You point your AI agent at the Grafana Cloud MCP endpoint, authorize in your browser, and your agent connects. ## How Grafana Cloud MCP differs from the local OSS server The following table compares the Grafana Cloud MCP server with the local OSS MCP server. Expand table | Aspect | Grafana Cloud MCP server | Local OSS MCP server | |--------------------|-------------------------------------------------------------------------------|----------------------------------------------------------------------------| | **Installation** | None required. Fully hosted. | Requires local installation and configuration. | | **Authentication** | OAuth 2.1 authorization flow. | Manual authentication (user/password or service account token). | | **Access scope** | User-scoped. The agent has only the permissions your Grafana RBAC grants you. | Service account-scoped. Access is determined by the service account token. | | **Deployment** | Grafana Cloud only. | Any Grafana instance (Cloud or self-hosted). | ## Before you begin Ensure you have the following: - **Grafana Cloud**: The Grafana Cloud MCP server works only with hosted Grafana Cloud environments. Self-hosted Grafana users should use the [local OSS MCP server](https://github.com/grafana/mcp-grafana) - **Terms and conditions**: An administrator must accept the Grafana Assistant terms and conditions - **Permissions**: You need the **Assistant Cloud MCP User** role or the `grafana-assistant-app.cloud-mcp:access` permission. Users with the **Editor** role or higher have this permission by default. Refer to [Manage Assistant access with RBAC](/docs/grafana-cloud/machine-learning/assistant/privacy-and-security/rbac) for details - **MCP client**: You need an MCP-compatible client, for example, [Cursor](https://www.cursor.com/), [Claude Desktop](https://claude.ai/download), [Windsurf](https://codeium.com/windsurf), or [Goose](https://block.github.io/goose/) > Note > > Using the Grafana Cloud MCP server counts toward your Grafana Assistant usage. Each user who connects through MCP is counted as an active user for billing purposes. Refer to [Pricing](/docs/grafana-cloud/machine-learning/assistant/pricing) for details on billing, fair usage limits, and how to monitor usage. ## Connect your AI agent The following steps connect your AI agent to the Grafana Cloud MCP server. 1. Configure your MCP client using one of the methods below. 2. Run a prompt in your AI agent that requires Grafana data. 3. When prompted, authorize the connection in your browser. Your AI agent is now connected to your Grafana data. ### Quick install Some clients support one-click or one-command installation: - **Cursor**: [Install Grafana MCP in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=grafana&config=eyJ1cmwiOiJodHRwczovL21jcC5ncmFmYW5hLmNvbS9tY3AifQ%3D%3D) - **Claude Code**: Run `claude mcp add grafana --transport http https://mcp.grafana.com/mcp` in your terminal ### Client configuration Add the Grafana MCP server to your client’s configuration. Use the **Streamable HTTP** transport type (SSE isn’t supported). Replace `` with your Grafana Cloud stack name. The `X-Grafana-URL` header is optional but recommended — it skips the URL entry step during authorization and redirects you directly to the consent page. Cursor Claude-Desktop Claude-Code Windsurf VS-Code ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy Cursor ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```cursor { "mcpServers": { "grafana": { "url": "https://mcp.grafana.com/mcp", "headers": { "X-Grafana-URL": "https://.grafana.net" } } } } ``` Claude-Desktop ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```claude-desktop { "mcpServers": { "grafana": { "type": "http", "url": "https://mcp.grafana.com/mcp", "headers": { "X-Grafana-URL": "https://.grafana.net" } } } } ``` Claude-Code ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```claude-code claude mcp add grafana \ --transport http \ --header "X-Grafana-URL: https://.grafana.net" \ https://mcp.grafana.com/mcp ``` Windsurf ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```windsurf { "mcpServers": { "grafana": { "url": "https://mcp.grafana.com/mcp", "headers": { "X-Grafana-URL": "https://.grafana.net" } } } } ``` VS-Code ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```vs-code { "servers": { "grafana": { "type": "http", "url": "https://mcp.grafana.com/mcp", "headers": { "X-Grafana-URL": "https://.grafana.net" } } } } ``` **Where to add the configuration:** - **Cursor**: **Settings** > **Features** > **MCP** > **+ Add New MCP Server**, or add to `.cursor/mcp.json` - **Claude Desktop**: Add to `claude_desktop_config.json` - **Claude Code**: Run the command in your terminal - **Windsurf**: Add to `~/.codeium/windsurf/mcp_config.json` - **VS Code**: Add to `.vscode/mcp.json` in your workspace For any other MCP-compatible client, set the endpoint to `https://mcp.grafana.com/mcp` with the **Streamable HTTP** transport type, and optionally set the `X-Grafana-URL` header to your Grafana Cloud instance URL. ## Configure read and write access When you authorize a Grafana Cloud MCP connection, the consent page shows the permissions the client is requesting. You can choose which permissions to grant: - **Read access**: View dashboards, alerts, incidents, and query data sources. Always available - **Write access**: Create and modify dashboards, alerts, and incidents. You can uncheck this to grant read-only access If you don’t check **Write access**, the agent can only query and browse your Grafana data. Write tools, for example, `update_dashboard` and `create_incident`, aren’t available. Organization Admins can grant write access by default. If the **Write access** checkbox is disabled on the consent page, ask your administrator to assign you the **Assistant Admin** role. Refer to [Manage Assistant access with RBAC](/docs/grafana-cloud/machine-learning/assistant/privacy-and-security/rbac) for details. ## Explore available tools The Grafana Cloud MCP server exposes the same tool categories as the [open source Grafana MCP server](https://github.com/grafana/mcp-grafana), plus Assistant-native tools, for example, infrastructure memory. Tools marked **Write** require the `grafana:write` scope. ### Search and navigation Use these tools to find dashboards, folders, and generate links to Grafana resources. Expand table | Tool | Description | |---------------------|---------------------------------------------------------------------| | `search_dashboards` | Search for dashboards by query string. | | `search_folders` | Search for folders by query string. | | `generate_deeplink` | Generate deeplink URLs for dashboards, panels, and Explore queries. | ### Dashboards and folders Use these tools to view and manage dashboards and folders. Expand table | Tool | Description | Access | |-------------------------------|----------------------------------------------------------------------------|-----------| | `get_dashboard_by_uid` | Retrieve the complete dashboard JSON by UID. | Read | | `get_dashboard_summary` | Get a compact summary of a dashboard without the full JSON. | Read | | `get_dashboard_property` | Extract specific parts of a dashboard using JSONPath expressions. | Read | | `get_dashboard_panel_queries` | Retrieve panel queries with template variable substitution. | Read | | `update_dashboard` | Create or update a dashboard using full JSON or targeted patch operations. | **Write** | | `create_folder` | Create a Grafana folder. | **Write** | ### Data sources Use these tools to list and inspect configured data sources. Expand table | Tool | Description | |--------------------|------------------------------------------------------------------------------| | `list_datasources` | List all configured data sources. Supports filtering by type and pagination. | | `get_datasource` | Get detailed information about a data source by UID or name. | ### Prometheus Use these tools to discover metrics and execute PromQL queries. Expand table | Tool | Description | |-----------------------------------|--------------------------------------------------------------------------| | `list_prometheus_metric_names` | Discover available metrics with regex filtering and pagination. | | `list_prometheus_metric_metadata` | List metadata about currently scraped metrics. | | `list_prometheus_label_names` | List label names with optional series selector and time range filtering. | | `list_prometheus_label_values` | Get values for a specific label. | | `query_prometheus` | Execute PromQL instant or range queries. | | `query_prometheus_histogram` | Query histogram percentiles. | ### Loki Use these tools to query logs and discover label metadata. Expand table | Tool | Description | |--------------------------|---------------------------------------------------------| | `list_loki_label_names` | List available label names in logs. | | `list_loki_label_values` | Get unique values for a specific label. | | `query_loki_logs` | Execute LogQL queries for log entries or metric values. | | `query_loki_stats` | Get statistics about log streams. | | `query_loki_patterns` | Detect and analyze common log patterns. | ### Tempo If you have Tempo data sources in your Grafana Cloud stack, the Grafana Cloud MCP server will proxy any tools offered by that Tempo data source. ### Pyroscope Use these tools to query profiling data. Expand table | Tool | Description | |--------------------------------|-------------------------------------------| | `list_pyroscope_label_names` | List available label names in profiles. | | `list_pyroscope_label_values` | List values for a specific label. | | `list_pyroscope_profile_types` | List available profile types. | | `query_pyroscope` | Query profiles or metrics from Pyroscope. | ### ClickHouse Use these tools to query ClickHouse datasources. Expand table | Tool | Description | |-----------------------------|-----------------------------------------------------| | `list_clickhouse_tables` | List available tables with metadata. | | `describe_clickhouse_table` | Get column schema for a table. | | `query_clickhouse` | Execute SQL queries against ClickHouse datasources. | ### CloudWatch Use these tools to query AWS CloudWatch metrics. Expand table | Tool | Description | |------------------------------|-----------------------------------| | `list_cloudwatch_namespaces` | List available AWS namespaces. | | `list_cloudwatch_metrics` | List metrics for a namespace. | | `list_cloudwatch_dimensions` | List dimension keys for a metric. | | `query_cloudwatch` | Query AWS CloudWatch metrics. | ### Elasticsearch Use this tool to search Elasticsearch datasources. Expand table | Tool | Description | |-----------------------|-------------------------------------------------------------------------| | `query_elasticsearch` | Execute Lucene or Query DSL searches against Elasticsearch datasources. | ### Alerting Use these tools to view and manage alert rules and routing configuration. Expand table | Tool | Description | Access | |---------------------------|-------------------------------------------------------------------------------------------------|------------------| | `alerting_manage_rules` | List, filter, and manage alert rules. With write scope, supports creating and updating rules. | Read / **Write** | | `alerting_manage_routing` | View alerting routing configuration, notification policies, contact points, and time intervals. | Read | ### Annotations Use these tools to view and create annotations on dashboards. Expand table | Tool | Description | Access | |-----------------------|-------------------------------------------------------------------|-----------| | `get_annotations` | Fetch annotations filtered by dashboard UID, time range, or tags. | Read | | `get_annotation_tags` | Get annotation tags with optional filtering. | Read | | `create_annotation` | Create a new annotation on a dashboard or panel. | **Write** | | `update_annotation` | Update properties of an existing annotation. | **Write** | ### Incidents Use these tools to view and manage incidents. Expand table | Tool | Description | Access | |----------------------------|------------------------------------------------|-----------| | `list_incidents` | List incidents with optional status filtering. | Read | | `get_incident` | Get full incident details by ID. | Read | | `create_incident` | Create a new incident. | **Write** | | `add_activity_to_incident` | Add a note to an incident’s timeline. | **Write** | ### OnCall Use these tools to view on-call schedules, shifts, teams, and alert groups. Expand table | Tool | Description | |----------------------------|--------------------------------------------------------------------------| | `list_oncall_schedules` | List OnCall schedules with optional team filtering. | | `get_oncall_shift` | Get detailed shift information. | | `get_current_oncall_users` | Get users currently on-call for a schedule. | | `list_oncall_teams` | List OnCall teams. | | `list_oncall_users` | List OnCall users with optional filtering. | | `list_alert_groups` | List alert groups with filtering by state, team, time range, and labels. | | `get_alert_group` | Get a specific alert group by ID. | ### Sift Use these tools to list and retrieve Sift investigations and analyses. Expand table | Tool | Description | Access | |----------------------------|-----------------------------------------------------|-----------| | `list_sift_investigations` | List Sift investigations. | Read | | `get_sift_investigation` | Retrieve a Sift investigation by UUID. | Read | | `get_sift_analysis` | Retrieve a specific analysis from an investigation. | Read | | `find_error_pattern_logs` | Search Loki logs for elevated error patterns. | **Write** | | `find_slow_requests` | Search Tempo datasources for slow requests. | **Write** | ### Other tools Use these tools for additional Grafana tasks, including panel rendering and infrastructure summaries. Expand table | Tool | Description | Access | |---------------------------|-----------------------------------------------------------------------------------------------|-----------| | `ask_assistant` | Send a prompt to Grafana Assistant and get the full reply, including tool use and reasoning. | **Write** | | `get_assertions` | Get assertion summary for an entity. | Read | | `get_panel_image` | Render a dashboard panel as a PNG image. | Read | | `describe_infrastructure` | Retrieve pre-built summaries of service groups including topology, metrics, and dependencies. | Read | | `get_query_examples` | Get example queries for datasource types. | Read | ## Manage connections Manage your Grafana Cloud MCP connections from the Grafana Assistant **Settings** → **External connections** → **MCP connections** page in your Grafana Cloud stack. ### Revoke access To revoke a Grafana Cloud MCP connection before it expires, go to **Settings** → **External connections** → **MCP connections** and find the connection in the list. ### Session lifetime Your OAuth token is valid for 1 hour and refreshes automatically for 30 days. After 30 days, you’re prompted to log in and re-authorize. ## Data privacy Grafana securely routes your MCP queries via proxy. Grafana doesn’t train AI models on your PromQL, LogQL queries, or prompt payload data. Refer to [Privacy and security](/docs/grafana-cloud/machine-learning/assistant/privacy-and-security) for more information. ## Billing and usage The Grafana Cloud MCP server is part of Grafana Assistant. Users who connect through MCP are counted as [active users](/docs/grafana-cloud/machine-learning/assistant/pricing/#active-users) and contribute to your organization’s monthly usage. The same fair usage limits and plan-level allowances apply whether you interact with Assistant through the Grafana UI or through an MCP client. To monitor usage across all Assistant surfaces including MCP, navigate to **Assistant > Usage** in your Grafana Cloud stack. Refer to [Pricing](/docs/grafana-cloud/machine-learning/assistant/pricing) for full details on billing, limits, and access controls. ## Known limitations - **Grafana Cloud only**: The Grafana Cloud MCP server doesn’t support self-hosted Grafana instances. Self-hosted users should use the [local OSS MCP server](https://github.com/grafana/mcp-grafana) - **Transport**: Only Streamable HTTP is supported. SSE transport isn’t supported ## Next steps - [Pricing and usage](/docs/grafana-cloud/machine-learning/assistant/pricing) - [Query data](/docs/grafana-cloud/machine-learning/assistant/guides/querying) - [Run investigations](/docs/grafana-cloud/machine-learning/assistant/guides/investigation) - [Navigate Grafana resources](/docs/grafana-cloud/machine-learning/assistant/guides/navigation)