Grafana Cloud

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:

JSON
{
  "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. Access level decides which operations your agent can perform. Tool areas choose which kinds of tools it can use, for example, dashboards or alerting. A tool needs both the required access level and a granted area. Your existing Grafana resource permissions still apply to every operation.

AccessWhat your agent can do
ReadInspect Grafana resources and query read-only data sources, for example, Prometheus, Loki, Tempo, and Pyroscope.
QueryAlso run raw queries, for example, SQL and InfluxQL. These execute as written and can change data if the data source credentials allow it.
WriteAlso create, change, and delete resources. Includes read and query access.

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

When Tool areas appears, select only the areas your agent needs. You must select at least one area to continue. Your client’s request can limit the available areas. Areas you can’t grant under your administrator’s restrictions appear unavailable, and areas you can grant only in part name the tools you can’t use. For details, refer to Restrict the tools users can grant.

You can also limit which kinds of tools the connection sees by choosing tool areas. For details, refer to Choose Grafana Cloud MCP tool areas.

Explore observability tools

Ask your agent to discover the tools available on your connection. The tool list depends on your granted access level, tool areas, and enabled features. If a tool is missing, it may be outside your granted areas. To change those areas, revoke the connection, reconnect, and authorize only the areas you need. The following tools extend dashboard and data source queries with app-specific context.

ToolWhat you can do
app_observability_handlerList services and inspect operations, dependencies, instrumentation quality, and runtimes.
app_observability_operation_handlerFind top operations and inspect a specific operation’s metrics.
frontend_observability_handlerFind apps and inspect Web Vitals and browser errors. With write access, create an app and get its instrumentation snippets.
kubernetes_handlerInspect 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.

For CloudWatch, use query_cloudwatch for metrics and query_cloudwatch_logs to run CloudWatch Logs Insights queries. Use list_cloudwatch_log_groups and list_cloudwatch_log_group_fields to find log groups and the fields you can query in them.

Attach data sources and incidents as resources

The server exposes each data source you can access as an MCP resource at grafana://datasources/<UID>, and each active IRM incident at grafana://irm/incidents/<ID>, so you can tell your agent what to work on instead of having it search.

In clients that offer a resource picker, for example, Claude Code, type @ and choose a data source or incident to attach its details to your prompt. Each data source entry shows the data source name and type, and marks your default data source. Each incident entry shows the incident title and severity. Other clients might instead let your agent list and read resources itself.

A data source resource contains the same details that get_datasource returns, including the type, URL, and settings. An incident resource contains the same details that get_incident returns, including the status, severity, labels, and custom fields. The picker lists active incidents, excluding drills, that started in the last 30 days, but your agent can read any incident by its URI, including resolved ones.

Resources follow the same access as the matching tool: if your connection can’t use get_datasource or get_incident, it doesn’t list or read that kind of resource.

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 run_gcx_command 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.

This tool was previously named exec_gcx. Calls to the old name still work, but if your client allows or blocks tools by name, update those rules to run_gcx_command.

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

JSON
{
  "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 run_gcx_command. Data source queries through gcx require query or write access, and resource changes require write access. If run_gcx_command isn’t listed, it isn’t available for your connection.

Like the gcx CLI, hosted gcx sends Grafana Labs usage statistics for each command, for example, the command path and flag names, never flag values or arguments. All hosted commands report the same device ID, so the statistics don’t carry an identifier for your stack.

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.

Send feedback about Grafana Cloud MCP

Your agent can tell Grafana Labs when a tool is missing, broken, or confusing by calling send_feedback. Every connection can use it, whatever its access and tool areas.

The agent describes what it was trying to do and what went wrong, picks a kind and an impact, and can name the tool the feedback is about. Feedback is stored with your stack and user account, so ask your agent to leave out credentials, personal data, and query results.

Next steps

Continue with these guides to configure access and work with Assistant results.