---
title: "Use Grafana Cloud MCP tools | Grafana Cloud documentation"
description: "Connect external AI agents to Grafana Cloud and use hosted gcx, observability tools, data source and incident resources, 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. **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.

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 any data source** 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).

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

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.

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 ![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 `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](https://grafana.com/docs/grafana-cloud/as-code/observability-as-code/grafana-cli/gcx/anonymous-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 [Manage Grafana Assistant pricing, usage, and limits](https://grafana.com/docs/grafana-cloud/platform/grafana-assistant/pricing).

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

- [Manage Assistant access with RBAC](https://grafana.com/docs/grafana-cloud/platform/grafana-assistant/privacy-and-security/rbac)
- [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)
