Use Grafana Cloud MCP tools

The Grafana Cloud MCP server connects your external AI agent to Grafana Cloud without a local server. You can query metrics, logs, traces, and profiles, work with dashboards and alerts, and use Grafana Assistant from your preferred MCP client.

This guide covers the hosted server’s tools. To connect an external MCP server to Assistant instead, refer to MCP servers.

Before you begin

You need a Grafana Cloud stack with Assistant available, any required Assistant terms accepted, and an MCP-compatible client. Your account needs the Assistant Cloud MCP User role or the grafana-assistant-app.cloud-mcp:access permission. Editors and administrators have this permission by default. For access requirements, refer to Manage Assistant access with RBAC.

To use interactive charts and alert apps, your client must also support MCP Apps. Tools for a specific Grafana app require that app to be installed and configured, and your account needs permission to use it.

Connect your AI agent

Add a remote MCP server to your client with the Streamable HTTP transport and the endpoint https://mcp.grafana.com/mcp. Complete the OAuth authorization in your browser. Your agent acts with your Grafana permissions and the access you grant to the connection.

For multiple stacks, add a separate server entry for each stack. Use the stack name in the endpoint path so your client treats each connection separately. Replace STACK_NAME with your stack name:

{
  "mcpServers": {
    "grafana": {
      "url": "https://mcp.grafana.com/mcp/<STACK_NAME>.grafana.net"
    }
  }
}

For client-specific setup and connection management, refer to Grafana Cloud MCP server.

Choose connection access

Choose the access your agent needs when you authorize the connection. Your Grafana permissions still apply to every operation.

Access	What your agent can do
Read	Inspect Grafana resources and query read-only data sources, for example, Prometheus, Loki, Tempo, and Pyroscope.
Query	Also run raw queries, for example, SQL and InfluxQL. These execute as written and can change data if the data source credentials allow it.
Write	Also create, change, and delete resources. Includes read and query access.

For read-only access, leave Read access selected and clear both Query access and Write access. To grant write access, you need the Assistant Admin role. For details, refer to Grafana Cloud MCP access.

Explore observability tools

Ask your agent to discover the tools available on your connection. The tool list depends on your granted access and enabled features. The following tools extend dashboard and data source queries with app-specific context.

Tool	What you can do
`app_observability_handler`	List services and inspect operations, dependencies, instrumentation quality, and runtimes.
`app_observability_operation_handler`	Find top operations and inspect a specific operation’s metrics.
`frontend_observability_handler`	Find apps and inspect Web Vitals and browser errors. With write access, create an app and get its instrumentation snippets.
`kubernetes_handler`	Inspect clusters, namespaces, Deployments, and pods, with links to Kubernetes Monitoring.

Application Observability features that use graph-backed inventory and topology also require Knowledge Graph. Native operation queries don’t require it.

You can also use native Tempo tools to search and compare traces, query trace-derived metrics, and explore trace attributes. For SQL data sources, use query_sql with query or write access.

Use interactive charts and alert apps

In clients that support MCP Apps, query_prometheus results can appear as interactive time series, heatmaps, bars, stats, or tables.

Ask your agent to use render_alert_status to inspect a Grafana-managed alert rule’s status, instances, and history. With write access and the required Grafana permissions, you can silence or unsilence the rule from the app.

Use render_alert_creation to open a Prometheus alert draft. Review the expression, threshold, folder, and notification settings before you create the rule. Opening the draft doesn’t save an alert. Simulating or creating the rule requires write access and the corresponding Grafana permissions.

For alerting workflows outside the apps, use alerting_rules_read and alerting_rules_write for rules, alerting_silences_read and alerting_silences_write for silences, and alerting_routing_write for routing changes. Write tools require write access.

Run hosted gcx commands

When no dedicated tool covers your task, use exec_gcx to run the Grafana Cloud CLI against your connected stack. You don’t need to install gcx or log in separately. Hosted commands use your connection’s permissions.

Ask your agent to discover commands before running them. For example, pass these arguments to exec_gcx to list command areas:

{
  "args": ["help-tree", "--depth", "1", "-o", "text"]
}

Pass arguments without the gcx program name. Hosted gcx covers additional workflows, for example, SLO, IRM, Fleet Management, and Knowledge Graph. Prefer a dedicated MCP tool when one covers your task.

Hosted gcx runs in a sandbox. It can’t read your local files or run local setup commands. Commands that require separate Grafana Cloud credentials, for example, k6 and Synthetic Monitoring, aren’t supported through exec_gcx. Data source queries through gcx require query or write access, and resource changes require write access. If exec_gcx isn’t listed, it isn’t available for your connection.

Search context and use Assistant

Use assistant_search to search indexed infrastructure, dashboards, incidents, alert rules, and past investigations. This replaces the older describe_infrastructure tool on the hosted server.

For SQL analysis, use search_context to find business definitions and dashboard query context, search_sql_tables to discover indexed tables, and read_grafanafs_file to read a Knowledge Base file. These tools don’t run SQL. search_context requires Analyst mode to be available on your stack.

Use get_assistant_conversation to read an existing conversation and ask_assistant to send a prompt to Assistant. ask_assistant requires write access because Assistant can perform actions that change resources.

For investigations, use create_investigation with write access to start an analysis. Use wait_for_investigation to wait for it to finish and get_investigation_report to read its Markdown report. You can also list investigations and profiles, inspect lifecycle state, and retrieve evidence and conversation threads with read access, subject to your investigation permissions.

Using Grafana Cloud MCP counts toward your Assistant active-user usage. Tool calls consume Assistant tokens only when they invoke an Assistant model. For billing details, refer to Understand Grafana Assistant pricing and usage.