google__adk-docs/docs/integrations/grafana-cloud.md

catalog_title, catalog_description, catalog_icon, catalog_tags

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

Grafana Cloud MCP tool for ADK

Supported in ADKPythonTypeScript

The Grafana Cloud MCP server 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 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 instead. It runs locally and connects to any Grafana instance using a service account token.

Additional resources

• Grafana Cloud MCP Server Documentation
• Grafana Cloud