---
title: "Use Grafana Cloud MCP tools | Grafana Cloud documentation"
description: "Connect external AI agents to Grafana Cloud and use hosted gcx, observability tools, interactive charts, alerts, and Assistant investigations."
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# 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](https://grafana.com/docs/grafana-cloud/platform/grafana-assistant/configure/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](https://grafana.com/docs/grafana-cloud/platform/grafana-assistant/privacy-and-security/rbac/#enable-grafana-cloud-mcp-access).

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 ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```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](https://grafana.com/docs/grafana-cloud/ai-tools/mcp-servers/cloud-mcp/).

## Choose connection access

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

Expand table

| 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](https://grafana.com/docs/grafana-cloud/platform/grafana-assistant/privacy-and-security/rbac/#enable-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.

Expand table

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

JSON ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```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 `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](https://grafana.com/docs/grafana-cloud/platform/grafana-assistant/pricing).

## Next steps

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

- [Manage Assistant access with RBAC](https://grafana.com/docs/grafana-cloud/platform/grafana-assistant/privacy-and-security/rbac)
- [Assistant Investigations](https://grafana.com/docs/grafana-cloud/platform/grafana-assistant/platform/investigation)
- [Grafana Assistant Workspace](https://grafana.com/docs/grafana-cloud/platform/grafana-assistant/platform/workspace)