---
catalog_title: Grafana Cloud
catalog_description: Query metrics, logs, traces, and manage dashboards, alerts, and incidents from Grafana Cloud
catalog_icon: /integrations/assets/grafana-cloud.png
catalog_tags: ["observability", "mcp"]
---

# Grafana Cloud MCP tool for ADK

<div class="language-support-tag">
  <span class="lst-supported">Supported in ADK</span><span class="lst-python">Python</span><span class="lst-typescript">TypeScript</span>
</div>

The [Grafana Cloud MCP
server](https://grafana.com/docs/grafana-cloud/machine-learning/assistant/configure/cloud-mcp/)
connects ADK agents directly to your Grafana Cloud observability stack. Your
agent can query Prometheus metrics, search logs in Loki, trace requests with
Tempo, browse dashboards, manage alerts and incidents, and more, with over 60
tools available.

The server is fully hosted and requires no local installation, Docker
containers, or service account tokens. Authentication uses OAuth 2.1 with user-scoped
permissions through Grafana RBAC.

## Use cases

- **Investigate incidents**: Query metrics, logs, and traces to diagnose
  production issues. Correlate Prometheus alerts with Loki log patterns and
  Tempo traces in a single conversation.
- **Manage dashboards**: Search, inspect, and update Grafana dashboards
  programmatically. Extract panel queries, generate deep links, and render
  panels as images.
- **Monitor infrastructure**: List data sources, discover available metrics,
  explore label values, and build PromQL or LogQL queries interactively.
- **Respond to alerts**: View firing alert rules, check on-call schedules,
  create or update incidents, and add activity notes to incident timelines.

## Prerequisites

- Access to a [Grafana Cloud](https://grafana.com/products/cloud/) instance
- An administrator must accept the Grafana Assistant terms and conditions
- The **Assistant Cloud MCP User** role or
  `grafana-assistant-app.cloud-mcp:access` permission (users with **Editor**
  role or higher have this by default)

## Use with agent

=== "Python"

    === "Remote MCP Server"

        ```python
        from google.adk.agents import Agent
        from google.adk.tools.mcp_tool import McpToolset
        from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

        GRAFANA_URL = "https://<your-stack>.grafana.net"

        root_agent = Agent(
            model="gemini-flash-latest",
            name="observability_agent",
            instruction="Help users investigate issues using Grafana Cloud observability data",
            tools=[
                McpToolset(
                    connection_params=StreamableHTTPConnectionParams(
                        url="https://mcp.grafana.com/mcp",
                        headers={
                            "X-Grafana-URL": GRAFANA_URL,
                        },
                    ),
                )
            ],
        )
        ```

=== "TypeScript"

    === "Remote MCP Server"

        ```typescript
        import { LlmAgent, MCPToolset } from "@google/adk";

        const GRAFANA_URL = "https://<your-stack>.grafana.net";

        const rootAgent = new LlmAgent({
            model: "gemini-flash-latest",
            name: "observability_agent",
            instruction: "Help users investigate issues using Grafana Cloud observability data",
            tools: [
                new MCPToolset({
                    type: "StreamableHTTPConnectionParams",
                    url: "https://mcp.grafana.com/mcp",
                    transportOptions: {
                        requestInit: {
                            headers: {
                                "X-Grafana-URL": GRAFANA_URL,
                            },
                        },
                    },
                }),
            ],
        });

        export { rootAgent };
        ```

Replace `<your-stack>` with your Grafana Cloud stack name. The `X-Grafana-URL`
header is optional but recommended because it skips the URL entry step during OAuth
authorization and redirects directly to the consent page.

!!! note

    When the agent first connects, you'll be prompted to authorize the
    connection in your browser. Your OAuth token is valid for 1 hour and
    refreshes automatically for 30 days.

## Configuration

The Grafana Cloud MCP server supports read and write access scopes:

- **Read access**: View dashboards, alerts, incidents, and query data sources.
  Always available.
- **Write access**: Create and modify dashboards, alerts, and incidents. You can
  grant or withhold write access during the OAuth consent step.

If your agent only needs to query data, deny write access during authorization for a least-privilege setup.

## Available tools

### Search and navigation

Tool | Description
---- | -----------
`search_dashboards` | Search for dashboards by query string
`search_folders` | Search for folders by query string
`generate_deeplink` | Generate deep link URLs for dashboards, panels, and Explore queries

### Dashboards

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 | Read
`get_dashboard_property` | Extract specific parts of a dashboard using JSONPath | Read
`get_dashboard_panel_queries` | Retrieve panel queries with template variable substitution | Read
`update_dashboard` | Create or update a dashboard | Write
`create_folder` | Create a Grafana folder | Write

### Data sources

Tool | Description
---- | -----------
`list_datasources` | List all configured data sources with optional type filtering
`get_datasource` | Get detailed information about a data source by UID or name

### Prometheus

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
`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

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

Tool | Description
---- | -----------
`tempo_traceql-search` | Search for traces using TraceQL
`tempo_get-trace` | Retrieve a trace by ID
`tempo_get-attribute-names` | Discover available trace attributes
`tempo_get-attribute-values` | Get values for a trace attribute
`tempo_traceql-metrics-instant` | Run instant TraceQL metrics queries
`tempo_traceql-metrics-range` | Run range TraceQL metrics queries

### Pyroscope

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

### Alerting

Tool | Description | Access
---- | ----------- | ------
`alerting_manage_rules` | List, filter, create, and update alert rules | Read / Write
`alerting_manage_routing` | View notification policies, contact points, and time intervals | Read

### Incidents

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 timeline | Write

### OnCall

Tool | Description
---- | -----------
`list_oncall_schedules` | List on-call 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

### Additional tools

Tool | Description | Access
---- | ----------- | ------
`get_panel_image` | Render a dashboard panel as a PNG image | Read
`describe_infrastructure` | Retrieve summaries of service groups including topology and dependencies | Read
`get_annotations` | Fetch annotations filtered by dashboard, time range, or tags | Read
`create_annotation` | Create a new annotation on a dashboard or panel | Write
`query_clickhouse` | Execute SQL queries against ClickHouse data sources | Read
`query_cloudwatch` | Query AWS CloudWatch metrics | Read
`query_elasticsearch` | Execute searches against Elasticsearch data sources | Read

## Self-hosted Grafana

For self-hosted Grafana instances, use the open source [Grafana MCP
server](https://github.com/grafana/mcp-grafana) instead. It runs locally and
connects to any Grafana instance using a service account token.

## Additional resources

- [Grafana Cloud MCP Server Documentation](https://grafana.com/docs/grafana-cloud/machine-learning/assistant/configure/cloud-mcp/)
- [Grafana Cloud](https://grafana.com/products/cloud/)

