> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to the Grafana Cloud MCP server

The Grafana Cloud MCP connector routes your AI agent's tool calls to Grafana Cloud's own MCP server through Scalekit. Each user signs in to Grafana Cloud once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 138 tools.

**Authentication:** OAuth 2.1/DCR
**Categories:** Monitoring, Developer Tools
**Tools:** 138: 106 read, 11 write, 21 destructive
**Users sign in with:** OAuth
**OAuth app:** Your own Grafana Cloud MCP server app
**Built by:** Vendor MCP
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=GRAFANACLOUDMCP)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the Grafana Cloud MCP connection

   In **AgentKit > Connections**, create a Grafana Cloud MCP connection and copy its redirect URI. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

4. ### Register an OAuth app

   Grafana Cloud MCP server connections use your own OAuth app. Register one with Grafana Cloud MCP server and add the redirect URI you copied.

   Then enter the app's Client ID and Client Secret on the Grafana Cloud MCP connection.

5. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   import { createInterface } from 'node:readline/promises'

   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions

   const connector = 'grafanacloudmcp'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Grafana Cloud MCP:', link)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   await rl.question('Press Enter after authorizing...')
   rl.close()

   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'grafanacloudmcp_user_info',
     toolInput: {},
   })
   console.log(result)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()

   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions

   connection_name = "grafanacloudmcp"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Grafana Cloud MCP:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="grafanacloudmcp_user_info",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user signs in once. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'grafanacloudmcp_agento11y_manage_agents',
  toolInput: {
    operation: 'list',
  },
  connector: 'grafanacloudmcp',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="grafanacloudmcp_agento11y_manage_agents",
    tool_input={
        "operation": "list",
    },
    connection_name="grafanacloudmcp",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `grafanacloudmcp_agento11y_manage_agents`

Manage Agent Observability agents · Read-only

Read the agent catalog of Grafana Agent Observability (the grafana-agento11y-app plugin): which agents send telemetry, what their system prompts and tools are, how their prompt versions evolved, and how each version scored.

The catalog is derived from ingested telemetry, not from a registration step: an agent exists here once its generations have been seen. It answers "what is this agent", not "what did it do".

Operations:
- 'list': agents in this tenant, newest activity first. Each row carries the latest effective version, first and latest seen times, generation and version counts, tool count, a system prompt prefix, and token_estimate. Paginated via limit and cursor
- 'get': one agent version in full: the complete system prompt, every tool with its JSON schema, and the models it ran on. Returns the latest version unless 'version' is set
- 'list_versions': the version history of one agent, one row per effective version with its seen window, generation count, tool count, and token_estimate. Paginated
- 'list_version_scores': evaluation score aggregates per version, with per-evaluator score_key, pass and fail counts, and mean_score. Use it to compare how versions scored

Versions: an effective version is always 'sha256:<64 lowercase hex>', and only that form is accepted by 'get'; a declared version such as '1.4.2' is reported in the declared_version fields but cannot be looked up. The plugin derives the effective version from the first of these the telemetry carries: the version the SDK reported, a hash of the declared version, a hash of the system prompt. Adding, removing, or editing a tool never mints a new version. Editing the prompt mints one only for an agent that reports neither its own effective version nor a declared version, so an agent that declares '1.4.2' keeps one effective version across prompt edits.

Response size: 'get' returns the whole system prompt plus every tool schema, which can be tens of thousands of tokens. Check token_estimate.total from 'list' or 'list_versions' before fetching, and prefer the system_prompt_prefix in those rows when a prefix is enough.

Cross-referencing: an agent name from 'list' is the value of the agent = "<name>" filter in conversation search.

Pagination: when a response carries next_cursor, call the same operation again with cursor set to it. For 'list', also repeat the same name_prefix, start_time, and end_time using absolute RFC3339 times; the cursor is bound to those filters and a relative value such as now-7d or 7d re-resolves and is rejected.

Permissions: every operation is a read and needs grafana-agento11y-app.data:read (Agento11y Editor or Admin). This tool performs no writes.

When to use:
- Discovering which agent names exist before filtering conversations or generations by agent
- Reading the system prompt or tool inventory an agent ran with, or how they changed between versions
- Checking whether a new prompt version scores worse than the previous one

When NOT to use:
- Reading individual conversations, generations, or their scores
- Inspecting evaluators or the rules that schedule them

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `operation` (`string`, required): The operation to perform: 'list' for the agent catalog, 'get' for one agent version in full (system prompt, tools, models), 'list_versions' for the version history of one agent, 'list_version_scores' for evaluation score aggregates per version. One of: `list`, `get`, `list_versions`, `list_version_scores`.
- `agent_name` (`string`, optional): Agent name from 'list'. Required for 'get', 'list_versions', and 'list_version_scores'. An explicitly empty string selects the unnamed agent (telemetry with no agent name), which 'get' and 'list_versions' accept and 'list_version_scores' rejects.
- `cursor` (`string`, optional): Pagination cursor from a previous response's next_cursor, echoed back exactly (for 'list' and 'list_versions'). For 'list' also resend the same name_prefix, start_time, and end_time as the first call using absolute RFC3339 times; the cursor is bound to those filters and a relative value such as now-7d or 7d drifts between calls and is rejected.
- `end_time` (`string`, optional): End of the time range in RFC3339 or relative format (e.g. now). For 'list' it keeps agents last seen at or before this time and defaults to no upper bound. For 'list_version_scores' it ends the score window; passing it without start_time gives a 90-day window ending here.
- `limit` (`integer`, optional): Maximum number of results per page (default 50, capped at 200 by the API) (for 'list' and 'list_versions')
- `name_prefix` (`string`, optional): Agent name filter (for 'list'). Despite the parameter name, the API matches it case-insensitively anywhere in the name, so 'agent' also returns 'my-agent'.
- `start_time` (`string`, optional): Start of the time range in RFC3339 or relative format (e.g. now-7d). For 'list' it keeps agents last seen at or after this time and defaults to no lower bound. For 'list_version_scores' it starts the score window; omitting it does not mean no lower bound, because the API then either scopes to the agent's 50 most recent versions or falls back to a 90-day window.
- `version` (`string`, optional): Effective version 'sha256:<64 lowercase hex>' from 'list' or 'list_versions', accepted only by 'get'. Omit it for the latest version. Declared versions such as '1.4.2' are not accepted here; they are reported in the declared_version fields.

Example input: `{"operation":"list"}`

### `grafanacloudmcp_agento11y_manage_conversations`

Manage Agent Observability conversations · Read-only

List, search, and fetch LLM conversations from Grafana Agent Observability (the grafana-agento11y-app plugin).

Operations:
- 'list': recent conversations (lightweight; id, title, generation count, timestamps), paginated via limit and cursor
- 'search': search conversations by filter expression and time range; results include models, agents, error counts, rating and eval summaries, and trace IDs
- 'get': one conversation by ID with all its generations, including full prompts and outputs (can be large)

Filter syntax for 'search': key operator value, with the value in double quotes; multiple filters are separated by spaces and combined with AND.
Filter keys (trace): model, provider, agent, agent.version, status, error.type, error.category, duration, tool.name, operation, namespace, cluster, service
Filter keys (metadata): generation_count, eval.passed, eval.evaluator_id, eval.score_key, eval.score
Operators: =, !=, >, <, >=, <=, =~ (regex)
Example: status = "error" agent = "claude-code"

Pagination: when a response has next_cursor, fetch the next page by calling the same operation again with cursor set to next_cursor. For 'search', also repeat the same filters, start_time, and end_time as the first call, using absolute RFC3339 times; relative ranges like now-24h shift between calls and the cursor will be rejected.

When to use:
- Debugging an AI application: find failing or low-rated conversations, then inspect their generations
- Reviewing evaluation results and user ratings across conversations

When NOT to use:
- Fetching a single generation or its evaluation scores

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `operation` (`string`, required): The operation to perform: 'list' for recent conversations, 'search' to filter conversations by expression and time range, 'get' to fetch one conversation with all its generations by ID. One of: `list`, `search`, `get`.
- `conversation_id` (`string`, optional): The conversation ID (required for 'get' operation)
- `cursor` (`string`, optional): Pagination cursor from a previous response (for 'list' and 'search' operations). To fetch the next page set this to next_cursor. For 'search' also resend the same filters and start_time/end_time from the first call and use absolute RFC3339 times; relative ranges like now-24h invalidate the cursor.
- `end_time` (`string`, optional): End of the search time range in RFC3339 or relative format (e.g. now). Defaults to now (for 'search' operation)
- `filters` (`string`, optional): Filter expression (for 'search' operation). Format: key operator value with the value in double quotes, multiple filters separated by spaces. See the tool description for keys and operators.
- `limit` (`integer`, optional): Maximum number of results per page (default 50) (for 'list' and 'search' operations)
- `start_time` (`string`, optional): Start of the search time range in RFC3339 or relative format (e.g. now-6h). Defaults to now-24h (for 'search' operation)

Example input: `{"operation":"list"}`

### `grafanacloudmcp_agento11y_manage_generations`

Manage Agent Observability generations · Read-only

Fetch a single LLM generation and its evaluation scores from Grafana Agent Observability (the grafana-agento11y-app plugin).

Operations:
- 'get': full generation detail by ID, including prompt, output, model, and usage (can be large)
- 'scores': evaluation scores for a generation (evaluator, score key, score type, value, passed, explanation)

When to use:
- Drilling into one generation of a conversation
- Checking why an evaluation passed or failed for a specific generation

When NOT to use:
- Searching or listing conversations

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `generation_id` (`string`, required): The generation ID
- `operation` (`string`, required): The operation to perform: 'get' for the full generation detail, 'scores' for the evaluation scores of the generation. One of: `get`, `scores`.
- `cursor` (`string`, optional): Pagination cursor from a previous response (for 'scores' operation)
- `limit` (`integer`, optional): Maximum number of scores per page (default 50) (for 'scores' operation)

Example input: `{"generation_id":"<generation_id>","operation":"get"}`

### `grafanacloudmcp_alerting_manage_routing`

Manage alerting routing · Read-only

Manage Grafana alerting routing configuration, including notification policies, contact points and time intervals.

Notification policies define how alerts are grouped, routed, and which contact points receive them.
Time intervals define active/mute periods for alert notifications.

When to use:
- Understanding how alerts are routed to contact points/receivers
- Debugging why an alert went to a specific receiver
- Checking grouping, timing, or mute interval settings

Does not show alert rule configuration or state.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `operation` (`string`, required): The operation to perform: 'get_notification_policies' to retrieve the notification policy tree, 'get_contact_points' to list all contact points, 'get_contact_point' to get a specific contact point by name, 'get_time_intervals' to list all time intervals, 'get_time_interval' to get a specific time interval by name. One of: `get_notification_policies`, `get_contact_points`, `get_contact_point`, `get_time_intervals`, `get_time_interval`.
- `contact_point_title` (`string`, optional): Title of the contact point to retrieve (required for get_contact_point operation)
- `datasource_uid` (`string`, optional): Optional: UID of an Alertmanager-compatible datasource to query for receivers. If omitted, returns Grafana-managed contact points. Only used with get_contact_points.
- `limit` (`integer`, optional): The maximum number of results to return. Default is 100. Only used with get_contact_points.
- `name` (`string`, optional): Filter contact points by name (exact match). Only used with get_contact_points.
- `time_interval_name` (`string`, optional): Name of the time interval to retrieve (required for get_time_interval operation)

Example input: `{"operation":"get_notification_policies"}`

### `grafanacloudmcp_alerting_rules_read`

Read alert rules · Read-only

List and inspect Grafana alert rules with filtering capabilities.

When to use:
- Understanding why an alert is or isn't firing
- Auditing alert rule configuration (queries, conditions, labels, notification settings)
- Finding alert rules by state, folder, group, or name
- Comparing rule versions to see what changed

Read-only: does not create, update, or delete rules, and does not show notification routing.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `operation` (`string`, required): The operation to perform: 'list' to search/filter rules, 'get' to retrieve full rule details (state + configuration) by UID, or 'versions' to get the version history of a rule. One of: `list`, `get`, `versions`.
- `datasource_uid` (`string`, optional): Optional: UID of a Prometheus or Loki datasource to query for datasource-managed alert rules. If omitted, returns Grafana-managed rules.
- `folder_uid` (`string`, optional): Filter by exact folder UID (for 'list' operation). Mutually exclusive with search_folder.
- `label_selectors` (`array`, optional): Prometheus-style selectors to filter alert rules by labels. Each string is a selector e.g. '{severity="critical", team=~"backend.*"}'. All selectors must match (AND).
- `limit_alerts` (`integer`, optional): Limit alert instances per rule. For list: 0 omits alerts. For get: <=0 defaults to 200. Max 200.
- `matchers` (`array`, optional): Label matchers to filter alert instances. Each string is a Prometheus-style matcher e.g. 'severity="critical"', 'env!="dev"', 'team=~"backend.*"'. Requires Grafana 12.4+.
- `rule_group` (`string`, optional): Filter by exact rule group name (for 'list' operation)
- `rule_limit` (`integer`, optional): Maximum number of rules to return (default 200, max 200). Requires Grafana 12.4+ (for 'list' operation). Default: `200`.
- `rule_type` (`string`, optional): Filter by rule type (for 'list' operation). One of: `alerting`, `recording`.
- `rule_uid` (`string`, optional): The UID of the alert rule (required for 'get' and 'versions' operations)
- `search_folder` (`string`, optional): Search folders by path using partial matching (for 'list' operation). Requires Grafana 12.4+. Mutually exclusive with folder_uid.
- `search_rule_name` (`string`, optional): Search alert rule names/titles using partial matching. Requires Grafana 12.4+ (for 'list' operation)
- `states` (`array`, optional): Filter by alert state: firing, pending, normal, recovering, nodata, error (for 'list' operation)

Example input: `{"operation":"list"}`

### `grafanacloudmcp_alerting_silences_read`

Read alerting silences · Read-only

List and inspect Grafana alerting silences. A silence temporarily suppresses notifications for alerts whose labels match a set of matchers.

Operations:
- 'list': list existing silences. Optionally filter by rule_uid (matches the __alert_rule_uid__ label) or by matchers.
- 'get': retrieve a single silence by silence_id.

When to use:
- Inspecting which alerts are currently silenced and why

Read-only: does not create, update, or delete silences, and does not show alert rules or notification routing.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `operation` (`string`, required): The operation to perform: 'list' to list silences, 'get' to retrieve a silence by id. One of: `list`, `get`.
- `matchers` (`array`, optional): Optional label matchers used to filter listed silences. Only used with 'list'.
- `rule_uid` (`string`, optional): Optional: filter listed silences to those scoped to this alert rule UID (matches the __alert_rule_uid__ label). Only used with 'list'.
- `silence_id` (`string`, optional): The silence id (required for 'get')

Example input: `{"operation":"list"}`

### `grafanacloudmcp_analyze_loki_labels`

Analyze Loki label strategy · Read-only

Audits a Loki label strategy and optionally diagnoses query performance. Returns per-label verdicts, missing base labels, normalisation issues, and a recommended set. Pass datasourceUid for live cardinality or labels for static scoring; both may be combined.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, optional): Datasource UID (live mode).
- `endRfc3339` (`string`, optional): No description.
- `expectedBaseLabels` (`array`, optional): No description.
- `labels` (`array`, optional): Caller-supplied labels (static mode).
- `maxLabels` (`integer`, optional): No description.
- `perfMetrics` (`object`, optional): Runtime metrics; presence triggers perf diagnosis.
- `selector` (`string`, optional): Optional LogQL selector for stats / perf diagnosis.
- `startRfc3339` (`string`, optional): No description.

Example input: `{}`

### `grafanacloudmcp_app_observability_handler`

Application Observability services · Read-only

Inspect Application Observability services on this Grafana stack.

Commands: list finds services across Knowledge Graph scopes; get reports one service's RED metrics and topology; operations lists one service's native operations; dependencies reports its upstream callers or downstream services; quality reports instrumentation checks; runtime reports JVM or Node.js runtime metrics. Service inventory, identity, topology, quality, and runtime metadata require an active Knowledge Graph and Application Observability integration. Native operation metrics come from the configured Prometheus datasource and do not require Knowledge Graph. The optional namespace for native operations is a Prometheus job prefix, which may differ from a Knowledge Graph namespace. Results include links into the app.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `command` (`string`, required): list (every service) | get (RED KPIs for one service) | operations (RED KPIs per operation under one service) | dependencies (services upstream/downstream of one service) | quality (Knowledge Graph instrumentation-quality report for one service) | runtime (JVM/Node.js runtime metrics for one service). One of: `list`, `get`, `operations`, `dependencies`, `quality`, `runtime`.
- `datasourceUid` (`string`, optional): Pin the Prometheus datasource holding the App O11y metrics, when the tool reports several candidates
- `direction` (`string`, optional): For dependencies: upstream (callers of the service) or downstream (services it calls). Defaults to downstream. One of: `upstream`, `downstream`.
- `env` (`string`, optional): Knowledge Graph environment scope for list, get, dependencies, quality, or runtime. For runtime it selects service metadata but does not filter native metrics.
- `limit` (`integer`, optional): For list, operations, and dependencies: cap rows after sorting, up to 50.
- `namespace` (`string`, optional): For list, get, dependencies, quality, and runtime: Knowledge Graph Service namespace scope, which need not equal the Kubernetes namespace, OTel service.namespace, or native job prefix. For operations: prefix of the native Prometheus job label (<namespace>/<service>).
- `service` (`string`, optional): Service name (required for get, operations, dependencies, quality, runtime; from the list command)
- `site` (`string`, optional): Knowledge Graph site scope for list, get, dependencies, quality, or runtime. For runtime it selects service metadata but does not filter native metrics.
- `sortBy` (`string`, optional): For list, operations, and dependencies: sort rows by request rate, error ratio, p95 latency, or name. Unset preserves the default order. One of: `rate`, `errors`, `p95`, `name`.
- `sortDirection` (`string`, optional): Sort direction for sortBy. Defaults to desc for RED metrics and asc for name. One of: `asc`, `desc`.

Example input: `{"command":"list"}`

### `grafanacloudmcp_app_observability_operation_handler`

Application Observability operations · Read-only

Inspect Application Observability operations on this Grafana stack.

Commands: top ranks operations across services by latency, errors, or request rate; get reports full RED metrics, including p99 latency, for one service and operationName. Both commands read native Prometheus span metrics independently of Knowledge Graph. The optional namespace is the native Prometheus job prefix, which may differ from a Knowledge Graph namespace. Results include links into the app.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `command` (`string`, required): top (slowest/highest-error/busiest operations across every service, unscoped to any one service) | get (full RED KPIs, including p99, for one already-identified operation under one service). One of: `top`, `get`.
- `datasourceUid` (`string`, optional): Pin the Prometheus datasource holding the App O11y metrics, when the tool reports several candidates
- `limit` (`integer`, optional): For top: cap the number of rows returned, applied after sorting. Defaults to 10 — this is a small triage view of the worst offenders, not a full inventory dump. Maximum 50.
- `namespace` (`string`, optional): Native Prometheus job prefix, not Knowledge Graph scope. For top: match jobs beginning <namespace>/; for get: select job <namespace>/<service>. It may differ from Kubernetes or OTel service namespace.
- `operation` (`string`, optional): Legacy direct-tool input for the operation/span name.
- `operationName` (`string`, optional): Required for get: the exact operation/span name to look up.
- `service` (`string`, optional): Required for get: the service the operation belongs to.
- `sortBy` (`string`, optional): For top: sort by request rate, error ratio, or p95 latency. Defaults to p95 (slowest first). One of: `rate`, `errors`, `p95`.
- `sortDirection` (`string`, optional): For top: sort direction. Defaults to desc (worst/busiest first). One of: `asc`, `desc`.

Example input: `{"command":"top"}`

### `grafanacloudmcp_assistant_search`

Assistant search · Read-only

Historical/indexed memory search across your Grafana stack: infrastructure/service groups, dashboards, past investigations, mostly-resolved IRM incidents, and alert-rule definitions.

Covers architecture, topology, dashboard discovery (including panel queries), alerts by meaning or content, past incidents, past investigations/RCAs, and broad "what do we know about X?" questions. Investigation and incident searches default to records created in the last three calendar months.

Results are indexed snapshots, not live telemetry, and can be stale or incomplete: an infrastructure result's dependency list comes from a sample of recent traces and can miss calls. Live metrics, logs, traces, alert state, and on-call or incident data are not searched.

Returns results grouped by collection with titles, summaries, links, and metadata (including datasource UIDs for infrastructure results).

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `collections` (`array`, required): Required, non-empty set of collections to search; there is no search-all value. dashboards: dashboards and their panel queries. alertRules: alert rule definitions. incidents: past incidents. investigations: past investigations and RCAs. infrastructure: indexed architecture, topology, and stored datasource mappings. Listing all five includes infrastructure.
- `query` (`string`, required): A natural-language search query describing what to find across infrastructure/service groups, dashboards, past investigations, incidents, and alert rules. Service names, error messages, and symptoms improve results.
- `endTime` (`string`, optional): Exclusive investigation and incident creation-time upper bound (RFC3339). Must be after startTime when both are supplied.
- `limits` (`object`, optional): Optional positive integer retrieval limits keyed by dashboards, infrastructure, investigations, incidents, or alertRules. Omitted entries keep existing defaults (20 dashboards, 3 infrastructure, 5 investigations, 5 incidents; alert rules use their retrieval limit). Limits are passed to collection retrieval backends, with no post-retrieval truncation. Filtering and deduplication may return fewer matches.
- `startTime` (`string`, optional): Inclusive investigation and incident creation-time lower bound (RFC3339). Defaults to the start of the last three calendar months.

Example input: `{"collections":[],"query":"*"}`

### `grafanacloudmcp_check_datasources_health`

Check datasources health · Read-only

Check datasource health. Filter by type or UIDs; omit both to check all.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `offset` (`integer`, optional): Number to skip for pagination. Default: `0`.
- `type` (`string`, optional): Plugin type filter; omit to check all
- `uids` (`array`, optional): UIDs to check

Example input: `{}`

### `grafanacloudmcp_describe_sql_table`

Describe SQL table · Read-only

Describe SQL columns: names, types, and available metadata. BigQuery includes nested field paths and descriptions; schema is the required dataset and database is the project.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): The UID of the SQL datasource.
- `table` (`string`, required): Table name to describe.
- `catalog` (`string`, optional): Data catalog name (Athena only).
- `database` (`string`, optional): Database name; BigQuery project (defaults to datasource defaultProject).
- `region` (`string`, optional): AWS region override (Athena only).
- `schema` (`string`, optional): Schema name (Snowflake, PostgreSQL, MSSQL); required dataset for BigQuery.

Example input: `{"datasourceUid":"<datasourceUid>","table":"<table>"}`

### `grafanacloudmcp_diff_tempo_traces`

Diff Tempo traces · Read-only

Compare two complete traces. Returns a compact summary and includes the full span-level patch when it is at most 64 KiB. Request trace-patch-v0 only when full details are required; full patches are not size-bounded.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `base_trace_id` (`string`, required): Trace ID for the baseline trace
- `compare_trace_id` (`string`, required): Trace ID for the comparison trace
- `datasourceUid` (`string`, required): UID of the tempo datasource to query
- `base_end` (`string`, optional): Optional end of the baseline trace search range in RFC3339 format. Must be provided with base_start.
- `base_start` (`string`, optional): Optional start of the baseline trace search range in RFC3339 format. Must be provided with base_end.
- `compare_end` (`string`, optional): Optional end of the comparison trace search range in RFC3339 format. Must be provided with compare_start.
- `compare_start` (`string`, optional): Optional start of the comparison trace search range in RFC3339 format. Must be provided with compare_end.
- `format` (`string`, optional): Output format. The composed format returns a compact summary and attaches the full patch only when it is at most 64 KiB. trace-patch-v0 has no output-size guarantee. One of: `trace-summary-v0-composed`, `trace-summary-v0-native`, `trace-patch-v0`. Default: `trace-summary-v0-composed`.

Example input: `{"base_trace_id":"<base_trace_id>","compare_trace_id":"<compare_trace_id>","datasourceUid":"<datasourceUid>"}`

### `grafanacloudmcp_get_alert_group`

Get IRM alert group · Read-only

Get a specific alert group from Grafana OnCall by its ID. Returns the full alert group details, including the most recent alert and its raw payload when the OnCall API provides them. Alert payloads carry integration-specific fingerprints (for example Sentry's payload.data.event.hashes or Alertmanager's payload.alerts[].fingerprint) that identify recurring alerts across different alert groups.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `alertGroupId` (`string`, required): The ID of the alert group to retrieve

Example input: `{"alertGroupId":"<alertGroupId>"}`

### `grafanacloudmcp_get_annotation_tags`

Get Annotation Tags · Read-only

Returns annotation tags with optional filtering by tag name. Only the provided filters are applied.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `limit` (`integer`, optional): Max results, default 100
- `tag` (`string`, optional): Optional filter by tag name

Example input: `{}`

### `grafanacloudmcp_get_annotations`

Get Annotations · Read-only

Fetch Grafana annotations using filters such as dashboard UID, time range and tags.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `alertUid` (`string`, optional): Filter by alert UID
- `dashboardUid` (`string`, optional): Filter by dashboard UID
- `from` (`integer`, optional): Epoch ms start time
- `limit` (`integer`, optional): Max results default 100
- `matchAny` (`boolean`, optional): If true, match any tag (OR). If false, match all tags (AND). Default: false
- `panelId` (`integer`, optional): Filter by panel ID
- `tags` (`array`, optional): Filter by tags. Multiple tags allowed; use matchAny to control AND/OR logic
- `to` (`integer`, optional): Epoch ms end time
- `type` (`string`, optional): annotation or alert
- `userId` (`integer`, optional): Filter by creator user ID

Example input: `{}`

### `grafanacloudmcp_get_assertions`

Get assertions summary · Read-only

Get assertion summary for a given entity with its type, name, env, site, namespace, and a time range

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `endTime` (`string`, required): The end time in RFC3339 format (e.g. 2024-01-01T00:00:00Z) or relative format (e.g. now)
- `startTime` (`string`, required): The start time in RFC3339 format (e.g. 2024-01-01T00:00:00Z) or relative format (e.g. now-1h)
- `entityName` (`string`, optional): The name of the entity to list
- `entityType` (`string`, optional): The type of the entity to list (e.g. Service, Node, Pod, etc.)
- `env` (`string`, optional): The env of the entity to list
- `namespace` (`string`, optional): The namespace of the entity to list
- `site` (`string`, optional): The site of the entity to list

Example input: `{"endTime":"2024-01-01T23:59:59Z","startTime":"2024-01-01T00:00:00Z"}`

### `grafanacloudmcp_get_assistant_conversation`

Read Grafana Assistant conversation · Read-only

Read the transcript of an existing Grafana Assistant conversation by ID.

Covers conversations started anywhere, including the Assistant sidebar in Grafana. Returns the user-visible messages in order as prose; includeToolCalls adds the assistant's tool calls and results.

The conversationId is the same identifier used as an Assistant conversation's contextId.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `conversationId` (`string`, required): The conversation ID to read; the same identifier as an Assistant conversation's contextId.
- `includeToolCalls` (`boolean`, optional): Optional. Include the assistant's tool calls and tool results in the transcript. Defaults to false (prose only).

Example input: `{"conversationId":"<conversationId>"}`

### `grafanacloudmcp_get_current_oncall_users`

Get current on-call users · Read-only

Get the list of users currently on-call for a specific Grafana OnCall schedule ID. Returns the schedule ID, name, and a list of detailed user objects for those currently on call.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `scheduleId` (`string`, required): The ID of the schedule to get current on-call users for

Example input: `{"scheduleId":"<scheduleId>"}`

### `grafanacloudmcp_get_dashboard_by_uid`

Get dashboard details · Read-only

Retrieves the complete dashboard, including panels, variables, and settings, for a specific dashboard identified by its UID. Pass optional version to load a saved snapshot instead of the current dashboard. Saved snapshots are fetched through Grafana's legacy versions API, so 'apiVersion' is omitted and 'meta' is partial: only version, createdBy, and created are populated. For current (non-versioned) fetches, the response includes 'apiVersion' and 'isV2': when 'isV2' is true the dashboard uses the v2 schema (panels live under 'elements' keyed by name, arranged by 'layout'; variables under 'variables'), otherwise it is classic v1 ('panels[]' with 'templating.list'). The full JSON of a large dashboard can be very large.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `uid` (`string`, required): The UID of the dashboard
- `version` (`integer`, optional): Optional saved version. Omit for the current dashboard

Example input: `{"uid":"<uid>"}`

### `grafanacloudmcp_get_dashboard_panel_queries`

Get dashboard panel queries · Read-only

Retrieve panel queries from a Grafana dashboard. Supports all datasource types (Prometheus, Loki, CloudWatch, SQL, etc.) and row-nested panels. Optionally filter to a specific panel by ID with `panelId`. Provide `variables` (an empty object uses saved selections) or `start`/`end` to populate `processedQuery` and `requiredVariables`. Referenced All selections return `warnings` requesting explicit values. Returns an array of objects with fields: title, query (raw expression), datasource (object with uid and type), and optionally processedQuery, refId, requiredVariables, and target. Targets built in a visual editor (CloudWatch metric search, InfluxDB query builder) have no string expression: those return an empty query plus `target`, the panel's raw query JSON. They can be executed as panel queries but not as standalone expressions.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `uid` (`string`, required): The UID of the dashboard
- `end` (`string`, optional): Query end time for macros (default now).
- `panelId` (`integer`, optional): Optional panel ID to filter to a specific panel
- `start` (`string`, optional): Query start time for macros (default now-1h).
- `variables` (`object`, optional): Optional variable substitutions (e.g., {"job": "api-server"})

Example input: `{"uid":"<uid>"}`

### `grafanacloudmcp_get_dashboard_property`

Get dashboard property · Read-only

Get specific parts of a dashboard using JSONPath expressions to minimize context window usage. JSONPath targets the dashboard's native schema. Classic v1 paths: '$.title' (title), '$.panels[*].title' (all panel titles), '$.panels[0]' (first panel), '$.templating.list' (variables), '$.annotations.list' (saved dashboard annotation queries/definitions), '$.tags' (tags), '$.panels[*].targets[*].expr' (all queries). v2 dashboards (isV2 true) use different paths: '$.title', '$.elements' (panels, keyed by name), '$.variables' (variables), '$.annotations'.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `jsonPath` (`string`, required): JSONPath expression to extract specific data (e.g., '$.panels[0].title' for first panel title, '$.panels[*].title' for all panel titles, '$.templating.list' for variables, '$.annotations.list' for saved dashboard annotation queries/definitions)
- `uid` (`string`, required): The UID of the dashboard

Example input: `{"jsonPath":"$.panels[0].title","uid":"<uid>"}`

### `grafanacloudmcp_get_dashboard_summary`

Get dashboard summary · Read-only

Get a compact summary of a dashboard including title, panel count, panel types, variables, and other metadata without the full JSON. Use this for dashboard overview and planning modifications without consuming large context windows.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `uid` (`string`, required): The UID of the dashboard

Example input: `{"uid":"<uid>"}`

### `grafanacloudmcp_get_datasource`

Get datasource · Read-only

Retrieves detailed information about a specific datasource by UID or name. Returns the full datasource model, including name, type, URL, access settings, JSON data, and secure JSON field status. Provide either uid or name; uid takes priority if both are given.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `name` (`string`, optional): The name of the datasource. Used if UID is not provided.
- `uid` (`string`, optional): The UID of the datasource. If provided, takes priority over name.

Example input: `{}`

### `grafanacloudmcp_get_doc`

Get Doc · Read-only

Fetch a Grafana documentation page. Set outline_only=true to get the heading structure first, then call again with a section name for bounded retrieval.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `url` (`string`, required): The grafana.com/docs/ URL to fetch
- `limit` (`integer`, optional): Max lines to return (default ~80)
- `offset` (`integer`, optional): Line offset for paging (0-indexed)
- `outline_only` (`boolean`, optional): Return only the heading outline (use to discover section names before fetching content)
- `section` (`string`, optional): Heading text to extract (returns only that section)

Example input: `{"url":"<url>"}`

### `grafanacloudmcp_get_incident`

Get incident details · Read-only

Get a single incident by ID. Returns the full incident details including title, status, severity, labels, custom fields, timestamps, and other metadata.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): The ID of the incident to retrieve

Example input: `{"id":"<id>"}`

### `grafanacloudmcp_get_investigation`

Get investigation · Read-only

Get one Grafana Assistant investigation (AI-driven root-cause investigation) by ID.

Returns the investigation's identifiers (investigationId and chatId), the authoritative row lifecycle state and metadata (title, description, state, summary, labels, team ownership, timestamps, completion quality, failure details), and the engine work snapshot (sessionStatus, mode, epoch, plan, report content).

The row's state field is authoritative for investigation lifecycle (pending, in_progress, completed, failed, cancelled, paused). The snapshot's sessionStatus only describes the engine session (idle, active, pause) and does not indicate completion or failure. Legacy (v1) investigations may have no snapshot; the row metadata is still returned with snapshotError set.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `investigationId` (`string`, required): Investigation ID.

Example input: `{"investigationId":"<investigationId>"}`

### `grafanacloudmcp_get_investigation_report`

Get investigation report · Read-only

Read the report of one Grafana Assistant investigation (AI-driven root-cause investigation) as markdown.

Returns the report plus the investigation's state, summary, completion quality, reportPending, and a url to open it in Grafana. The report is empty until the investigation writes one, which usually happens once it settles. An investigation can also settle without a report, for example when it answers directly; its summary then holds the answer. A follow-up turn can regenerate the report, in which case reportPending is true and the previous report is returned.

Reports cite evidence with [cite:pN] markers, and embedded panels appear as the same markers. Each marker is a panel ID in the investigation's evidence index.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `investigationId` (`string`, required): Investigation ID.

Example input: `{"investigationId":"<investigationId>"}`

### `grafanacloudmcp_get_investigation_thread`

Get investigation thread · Read-only

Get the working thread of one Grafana Assistant investigation (AI-driven root-cause investigation) by ID: the user-visible conversation between the investigation agent and its tools.

Resolves the investigation to its backing chat and returns the non-hidden user-visible messages in order. Each message keeps only prose (the agent's narrative and findings), tool calls (toolName and toolInput), and tool results (raw query output); internal reasoning and bookkeeping blocks are excluded. Tool results are returned verbatim and can be large; limit and offset page through long threads, and total reports the full user-visible count.

The thread holds the raw data behind a report's [cite:pN] citations: each evidence entry's toolUseId matches the tool_result block in this thread that holds the captured query output.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `investigationId` (`string`, required): Investigation ID.
- `limit` (`integer`, optional): Maximum number of messages to return. 0 or omitted returns all.
- `offset` (`integer`, optional): Number of user-visible messages to skip from the start of the thread.

Example input: `{"investigationId":"<investigationId>"}`

### `grafanacloudmcp_get_oncall_shift`

Get OnCall shift · Read-only

Get detailed information for a specific Grafana OnCall shift using its ID. A shift represents a designated time period within a schedule when users are actively on-call. Returns the full shift details.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `shiftId` (`string`, required): The ID of the shift to get details for

Example input: `{"shiftId":"<shiftId>"}`

### `grafanacloudmcp_get_panel_image`

Get panel or dashboard image · Read-only

Render a Grafana dashboard panel, full dashboard or Explore view as a PNG image. Returns the image as base64 encoded data. Requires the Grafana Image Renderer service to be installed. Exactly one of dashboardUid (for stored dashboards), provisioningPreview (for dashboards staged on a provisioning repository branch, e.g. a git-sync PR) or explore (an ad-hoc datasource query rendered in Explore, no saved dashboard needed) must be supplied. Defaults in CSS pixels: panel 1000x750, dashboard 1200x900, Explore 1000x1000. Scale defaults to 1 for all views and is clamped to 1-3. Use this for generating visual snapshots of dashboards for reports, alerts, or presentations.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `dashboardUid` (`string`, optional): The UID of a stored dashboard containing the panel. Required unless provisioningPreview is provided.
- `explore` (`object`, optional): Render an ad-hoc Explore view for a datasource and queries instead of a stored dashboard. Mutually exclusive with dashboardUid and provisioningPreview. Requires Grafana 10.2 or later.
- `height` (`integer`, optional): Positive viewport height in CSS pixels, or -1 for full-page rendering. See tool description for per-view defaults. Positive heights are capped so height times scale is at most 3000. The renderer may raise values below its configured minimum (500 by default).
- `panelId` (`integer`, optional): The ID of the panel to render. If omitted, the entire dashboard is rendered
- `provisioningPreview` (`object`, optional): Render a dashboard from a provisioning repository branch (e.g. a git-sync PR preview). Mutually exclusive with dashboardUid.
- `scale` (`integer`, optional): Image scale factor. See tool description for default and limits. Higher scales reduce the maximum allowed viewport dimensions.
- `theme` (`string`, optional): Theme for the rendered image: light or dark. Defaults to dark
- `timeout` (`integer`, optional): Rendering timeout in seconds. Defaults to 60, capped at 120
- `timeRange` (`object`, optional): Time range for the rendered image
- `variables` (`object`, optional): Dashboard variables to apply. Values can be a single string or an array of strings for multi-value variables (e.g., {"var-datasource": "prometheus", "var-instance": ["server1", "server2"]})
- `width` (`integer`, optional): Positive viewport width in CSS pixels. See tool description for per-view defaults. Capped so width times scale is at most 3000. The renderer may raise values below its configured minimum (1000 by default).

Example input: `{}`

### `grafanacloudmcp_get_plugin`

Get plugin · Read-only

Check whether a Grafana plugin is installed and retrieve its details (name, version, type, enabled status). Returns installed=false when the plugin is not found.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `pluginId` (`string`, required): The plugin ID to check (e.g. 'prometheus', 'grafana-piechart-panel', 'grafana-oncall-app')

Example input: `{"pluginId":"prometheus"}`

### `grafanacloudmcp_get_query_examples`

Get query examples · Read-only

Get example queries for a specific datasource type. Provides sample queries with descriptions for Prometheus (PromQL), Loki (LogQL), ClickHouse (SQL with Grafana macros), CloudWatch (metric configurations), and InfluxDB (Flux and InfluxQL). Use this to understand query syntax and common patterns for each datasource.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceType` (`string`, required): The datasource type to get examples for (e.g. 'prometheus', 'loki', 'clickhouse', 'cloudwatch', 'influxdb')

Example input: `{"datasourceType":"prometheus"}`

### `grafanacloudmcp_get_resource_description`

Get resource description · Read-only

List available permissions and assignment capabilities for a Grafana resource type.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `resourceType` (`string`, required): Type of Grafana resource to get description for. One of: `dashboards`, `datasources`, `folders`, `teams`, `users`, `serviceaccounts`.

Example input: `{"resourceType":"dashboards"}`

### `grafanacloudmcp_get_resource_permissions`

Get resource permissions · Read-only

List all permissions set on a specific Grafana resource (e.g., dashboard, datasource, folder) by its type and ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `resource` (`string`, required): Resource type (e.g. 'dashboards' 'datasources' 'folders')
- `resourceId` (`string`, required): Unique identifier of the resource (UID for dashboards/datasources/folders)

Example input: `{"resource":"dashboards","resourceId":"<resourceId>"}`

### `grafanacloudmcp_get_role_assignments`

Get role assignments · Read-only

List all assignments for a specific role, showing which users, teams, and service accounts have been assigned this role.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `roleUID` (`string`, required): Role UID to retrieve

Example input: `{"roleUID":"<roleUID>"}`

### `grafanacloudmcp_get_role_details`

Get role details · Read-only

Get detailed information about a specific Grafana role by its UID, including permissions, metadata, and configuration.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `roleUID` (`string`, required): Role UID to retrieve

Example input: `{"roleUID":"<roleUID>"}`

### `grafanacloudmcp_get_snapshot`

Get snapshot · Read-only

Get a Grafana snapshot by key, including snapshot metadata and dashboard payload.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `key` (`string`, required): Snapshot key to retrieve

Example input: `{"key":"<key>"}`

### `grafanacloudmcp_get_tempo_trace`

Get Tempo trace · Read-only

Retrieve a specific trace by ID. Returns its spans grouped by service and resource, with span attributes, events and links.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): UID of the tempo datasource to query
- `trace_id` (`string`, required): Trace ID to retrieve
- `end` (`string`, optional): Optional end of the trace search range in RFC3339 format. Must be provided with start.
- `focus_span_id` (`string`, optional): Optional 16-character hexadecimal span ID to select initially. The full trace remains available.
- `start` (`string`, optional): Optional start of the trace search range in RFC3339 format. Must be provided with end. Narrowing the range makes the lookup much cheaper.

Example input: `{"datasourceUid":"<datasourceUid>","trace_id":"<trace_id>"}`

### `grafanacloudmcp_get_tempo_traceql_docs`

Get TraceQL documentation · Read-only

Retrieve TraceQL reference documentation with examples, covering attribute filters, aggregates, structural operators, and metrics queries. Consult this before writing a non-trivial TraceQL query, or after one returns an error or no results.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `topic` (`string`, required): Which section of the TraceQL reference to retrieve: 'basic' for attribute and duration filters, 'aggregates' for count/avg/sum and by() grouping, 'structural' for parent/child and descendant operators, 'metrics' for rate/quantile_over_time metrics queries. One of: `basic`, `aggregates`, `structural`, `metrics`.

Example input: `{"topic":"basic"}`

### `grafanacloudmcp_kubernetes_handler`

Kubernetes Monitoring · Read-only

Inspect the Kubernetes Monitoring inventory on this Grafana stack.

The read-only list and get commands resolve the same levels: omit cluster for clusters, set cluster for namespaces, add namespace for Deployments, and add workload for pods of that Deployment. An optional datasourceUid selects a Prometheus datasource. The app must be installed and activated, and the caller needs the Kubernetes Monitoring read action for the requested level. Results include links into the app.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `command` (`string`, required): list (all clusters with their node, namespace and pod counts) or get (drill into one cluster, namespace, or Deployment). One of: `list`, `get`.
- `cluster` (`string`, optional): Cluster name (required for get; from the list command)
- `datasourceUid` (`string`, optional): Pin the Prometheus datasource holding the cluster metrics, when the tool reports several candidates
- `namespace` (`string`, optional): Namespace within the cluster (optional for get)
- `workload` (`string`, optional): Deployment name within the namespace (optional for get; lists that workload's pods)

Example input: `{"command":"list"}`

### `grafanacloudmcp_list_alert_groups`

List IRM alert groups · Read-only

List alert groups from Grafana OnCall with filtering options. Supports filtering by alert group ID, route ID, integration ID, state (new, acknowledged, resolved, silenced), team ID, time range, labels, and name. For time ranges, use format '{start}_{end}' ISO 8601 timestamp range (e.g., '2025-01-19T00:00:00_2025-01-19T23:59:59' for a specific day). For labels, use format 'key:value' (e.g., ['env:prod', 'severity:high']). Returns a list of alert group objects with their details. Supports pagination.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, optional): Filter by specific alert group ID
- `integrationId` (`string`, optional): Filter by integration ID
- `labels` (`array`, optional): Filter by labels in format key:value (e.g., ['env:prod', 'severity:high'])
- `name` (`string`, optional): Filter by alert group name
- `page` (`integer`, optional): The page number to return
- `routeId` (`string`, optional): Filter by route ID
- `startedAt` (`string`, optional): Filter by time range in format '{start}_{end}' ISO 8601 timestamp range (UTC assumed, no timezone indicator needed) (e.g., '2025-01-19T00:00:00_2025-01-19T23:59:59')
- `state` (`string`, optional): Filter by alert group state (one of: new, acknowledged, resolved, silenced)
- `teamId` (`string`, optional): Filter by team ID

Example input: `{}`

### `grafanacloudmcp_list_all_roles`

List all roles · Read-only

List all roles in Grafana. Optionally filter to show only roles that can be delegated by the current user. Returns role details including UID, name, permissions, and metadata.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `delegatableOnly` (`boolean`, optional): Optional: If set true only return roles that can be delegated by current user

Example input: `{}`

### `grafanacloudmcp_list_cloudwatch_dimension_values`

List CloudWatch dimension values · Read-only

List values for a CloudWatch dimension key (e.g. the specific cluster names behind a ClusterName dimension). Requires region. Supports cross-account monitoring via optional accountId parameter.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): The UID of the CloudWatch datasource
- `dimensionKey` (`string`, required): Dimension key to list values for (e.g. ClusterName)
- `metricName` (`string`, required): Metric name (e.g. CPUUtilization)
- `namespace` (`string`, required): CloudWatch namespace (e.g. AWS/ECS)
- `region` (`string`, required): AWS region (e.g. us-east-1)
- `accountId` (`string`, optional): AWS account ID for cross-account monitoring. Specify an account ID to filter dimension values from a specific source account, or 'all' for all linked accounts.

Example input: `{"datasourceUid":"<datasourceUid>","dimensionKey":"<dimensionKey>","metricName":"<metricName>","namespace":"<namespace>","region":"<region>"}`

### `grafanacloudmcp_list_cloudwatch_dimensions`

List CloudWatch dimensions · Read-only

List dimension keys for a CloudWatch metric. Requires region. Supports cross-account monitoring via optional accountId parameter.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): The UID of the CloudWatch datasource
- `metricName` (`string`, required): Metric name (e.g. CPUUtilization)
- `namespace` (`string`, required): CloudWatch namespace (e.g. AWS/ECS)
- `region` (`string`, required): AWS region (e.g. us-east-1)
- `accountId` (`string`, optional): AWS account ID for cross-account monitoring. Specify an account ID to filter dimensions from a specific source account, or 'all' for all linked accounts.

Example input: `{"datasourceUid":"<datasourceUid>","metricName":"<metricName>","namespace":"<namespace>","region":"<region>"}`

### `grafanacloudmcp_list_cloudwatch_log_group_fields`

List CloudWatch log group fields · Read-only

List the fields discovered in a CloudWatch log group, for use in Logs Insights queries. Requires region.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): The UID of the CloudWatch datasource
- `logGroupName` (`string`, required): The log group name to list fields for
- `region` (`string`, required): AWS region (e.g. us-east-1)

Example input: `{"datasourceUid":"<datasourceUid>","logGroupName":"<logGroupName>","region":"<region>"}`

### `grafanacloudmcp_list_cloudwatch_log_groups`

List CloudWatch log groups · Read-only

List CloudWatch log group names, optionally filtered by name prefix. Returns at most 50 log groups; use prefix to narrow larger accounts. Requires region. Supports cross-account monitoring via optional accountId parameter, which returns log group ARNs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): The UID of the CloudWatch datasource
- `region` (`string`, required): AWS region (e.g. us-east-1)
- `accountId` (`string`, optional): AWS account ID for cross-account monitoring. Specify an account ID to filter log groups from a specific source account, or 'all' for all linked accounts. When set, log group ARNs are returned instead of names.
- `prefix` (`string`, optional): Only return log groups whose name starts with this prefix

Example input: `{"datasourceUid":"<datasourceUid>","region":"<region>"}`

### `grafanacloudmcp_list_cloudwatch_metrics`

List CloudWatch metrics · Read-only

List metrics for a CloudWatch namespace. Requires region. Supports cross-account monitoring via optional accountId parameter.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): The UID of the CloudWatch datasource
- `namespace` (`string`, required): CloudWatch namespace (e.g. AWS/ECS, AWS/EC2)
- `region` (`string`, required): AWS region (e.g. us-east-1)
- `accountId` (`string`, optional): AWS account ID for cross-account monitoring. Specify an account ID to filter metrics from a specific source account, or 'all' for all linked accounts.

Example input: `{"datasourceUid":"<datasourceUid>","namespace":"<namespace>","region":"<region>"}`

### `grafanacloudmcp_list_cloudwatch_namespaces`

List CloudWatch namespaces · Read-only

List available CloudWatch namespaces (AWS/EC2, AWS/ECS, AWS/RDS, etc.). Requires region. Supports cross-account monitoring via optional accountId parameter.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): The UID of the CloudWatch datasource
- `region` (`string`, required): AWS region (e.g. us-east-1)
- `accountId` (`string`, optional): AWS account ID for cross-account monitoring. Specify an account ID to filter namespaces from a specific source account, or 'all' for all linked accounts.

Example input: `{"datasourceUid":"<datasourceUid>","region":"<region>"}`

### `grafanacloudmcp_list_dashboard_versions`

List dashboard versions · Read-only

List saved versions of a Grafana dashboard. Returns compact metadata: version number, author, timestamp, and save message. A version number can be passed to the dashboard fetch to load that snapshot.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `uid` (`string`, required): The UID of the dashboard
- `limit` (`integer`, optional): Maximum number of versions to return
- `start` (`integer`, optional): Version to start from. Only versions at or below this number are returned

Example input: `{"uid":"<uid>"}`

### `grafanacloudmcp_list_datasources`

List datasources · Read-only

List all configured datasources in Grafana. Use this to discover available datasources and their UIDs. Supports filtering by type and/or name (case-insensitive substring match) and pagination.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `limit` (`integer`, optional): Maximum number of datasources to return (max 100). Default: `50`.
- `name` (`string`, optional): Case-insensitive substring match on the datasource name. For example, 'prod' matches datasources named 'prometheus-prod-eu' and 'loki-prod-us'. Useful on instances with many datasources where filtering by type alone returns too many results.
- `offset` (`integer`, optional): Number of datasources to skip for pagination. Default: `0`.
- `type` (`string`, optional): The type of datasources to search for. For example, 'prometheus', 'loki', 'tempo', etc...

Example input: `{}`

### `grafanacloudmcp_list_graphite_metrics`

List Graphite metrics · Read-only

Discover available metric paths in a Graphite datasource by browsing the metric tree. Returns nodes matching the query pattern, each indicating whether it is a leaf metric (has data) or an expandable branch (has children). Use '*' as a wildcard at any level to enumerate the tree (e.g. '*' → top-level nodes, 'servers.*' → all second-level nodes under 'servers').

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): The UID of the Graphite datasource to query
- `query` (`string`, required): Metric path pattern to search. Use '*' as a wildcard at any level (e.g. '*' lists top-level nodes, 'servers.*' lists all servers, 'servers.web01.*' lists all metrics under web01).

Example input: `{"datasourceUid":"<datasourceUid>","query":"*"}`

### `grafanacloudmcp_list_graphite_tags`

List Graphite tags · Read-only

List available tag names in a Graphite datasource that uses tag-based metrics. Returns a list of tag name strings (e.g. ["name", "env", "region"]). These tags can be used to build tag-based target expressions (e.g. seriesByTag('name=cpu.load,env=prod')). Optionally filter by a prefix. Requires Graphite to be configured with tag support.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): The UID of the Graphite datasource to query
- `prefix` (`string`, optional): Optional prefix to filter tag names (e.g. 'env' returns tags whose name starts with 'env').

Example input: `{"datasourceUid":"<datasourceUid>"}`

### `grafanacloudmcp_list_incident_custom_fields`

List incident custom fields · Read-only

List the custom fields configured for Grafana incidents, including their type and, for select fields, the options that may be chosen.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `includeArchived` (`boolean`, optional): Whether to include archived custom fields. Archived fields cannot be set on new incidents but may still hold values on older ones

Example input: `{}`

### `grafanacloudmcp_list_incidents`

List incidents · Read-only

List Grafana incidents. Allows filtering by status ('active', 'resolved') and optionally including drill incidents. Returns a preview list with basic details, and custom field values if requested.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `drill` (`boolean`, optional): Whether to include drill incidents
- `includeCustomFields` (`boolean`, optional): Whether to include each incident's custom field values. Off by default because it costs an extra request and makes the response considerably larger
- `limit` (`integer`, optional): The maximum number of incidents to return. Default: `10`.
- `status` (`string`, optional): The status of the incidents to include. Valid values: 'active', 'resolved'

Example input: `{}`

### `grafanacloudmcp_list_investigation_evidence`

List investigation evidence · Read-only

List the evidence citation index for one Grafana Assistant investigation (AI-driven root-cause investigation) by ID.

Investigation reports cite captured query panels with [cite:pN] markers. Each evidence entry describes one captured panel, keyed by that panel ID: the tool that produced it (prometheus, loki, tempo, pyroscope), a human-readable query summary, the epoch (agent turn) at capture time, the capture timestamp, and the tool call ID that produced it.

This is an index, not the data: raw query results live in the investigation thread, in the tool result whose ID matches the entry's toolUseId. Legacy (v1) investigations have no engine session and return an empty list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `investigationId` (`string`, required): Investigation ID.

Example input: `{"investigationId":"<investigationId>"}`

### `grafanacloudmcp_list_investigation_profiles`

List investigation profiles · Read-only

List the agent profiles available for Grafana Assistant investigations (AI-driven root-cause investigations) on this Grafana Cloud stack.

Each profile describes an investigation agent configuration: its ID, display name, description, whether it is the default, its step budget, the tools it can use, and its content hash. A profile's ID is the agentProfileId accepted when creating an investigation.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `grafanacloudmcp_list_investigations`

List investigations · Read-only

List Grafana Assistant investigations (AI-driven root-cause investigations) on this Grafana Cloud stack.

Returns one summary per investigation — ID, chat ID, title, state, timestamps, labels, team ownership, progress, and completion quality — plus the total count of matches for pagination. Results are limited to investigations the authenticated user is allowed to see.

All filters are optional. chatId finds the investigation that owns a known chat (all other filters are then ignored), q is free-text search, state/scope/label/teamName/from/to narrow results, and limit/offset with the returned total paginate.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `archivedOnly` (`boolean`, optional): Return only investigations whose backing chat is archived. Overrides includeArchived when true.
- `chatId` (`string`, optional): Find the investigation owning this chat ID. Returns a singleton (or empty) list. When set, all other filters are ignored.
- `from` (`string`, optional): Only investigations created at or after this RFC3339 timestamp.
- `includeArchived` (`boolean`, optional): Include investigations whose backing chat is archived.
- `includeLegacy` (`boolean`, optional): Also include legacy (v1) investigations in results.
- `label` (`string`, optional): Filter by label in key:value format.
- `limit` (`integer`, optional): Maximum number of investigations to return.
- `offset` (`integer`, optional): Number of investigations to skip, for pagination.
- `order` (`string`, optional): Sort order: asc or desc.
- `q` (`string`, optional): Search text matched against investigation title, description, or chat name.
- `scope` (`string`, optional): Visibility scope: all, mine, teams, or system. One of: `all`, `mine`, `teams`, `system`.
- `sort` (`string`, optional): Sort field: createdAt, updatedAt, title, or state.
- `state` (`string`, optional): Filter by investigation state: pending, in_progress, completed, failed, cancelled, or paused.
- `teamName` (`string`, optional): Filter investigations to a specific team by name.
- `to` (`string`, optional): Only investigations created at or before this RFC3339 timestamp.
- `view` (`string`, optional): Response projection: full or lite. Lite omits agents and truncates description and source.prompt to 200 runes, appending an ellipsis when truncated.

Example input: `{}`

### `grafanacloudmcp_list_loki_label_names`

List Loki label names · Read-only

Lists all available label/field names (keys) found in logs within a specified Loki or VictoriaLogs datasource and time range. Returns a list of unique label strings (e.g., `["app", "env", "pod"]`). If the time range is not provided, it defaults to the last hour. Optionally narrow the search to a subset of streams with `matcher` (e.g. `{namespace="prod"}`).

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): The UID of the datasource to query
- `endRfc3339` (`string`, optional): Optionally, the end time of the query in RFC3339 format or relative time (e.g. 'now') (defaults to now)
- `matcher` (`string`, optional): Optionally, a stream selector to narrow the search to matching streams (Loki: LogQL, e.g. '{namespace="prod"}'; VictoriaLogs: LogsQL). Defaults to searching across all streams.
- `startRfc3339` (`string`, optional): Optionally, the start time of the query in RFC3339 format or relative time (e.g. 'now-1h') (defaults to 1 hour ago)

Example input: `{"datasourceUid":"<datasourceUid>"}`

### `grafanacloudmcp_list_loki_label_values`

List Loki label values · Read-only

Retrieves all unique values associated with a specific `labelName` within a Loki or VictoriaLogs datasource and time range. Returns a list of string values (e.g., for `labelName="env"`, might return `["prod", "staging", "dev"]`). Useful for discovering filter options. Defaults to the last hour if the time range is omitted. Optionally narrow the search to a subset of streams with `matcher` (e.g. `{namespace="prod"}`) — for example, to list `service` values seen only within a specific namespace.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): The UID of the datasource to query
- `labelName` (`string`, required): The name of the label to retrieve values for (e.g. 'app', 'env', 'pod')
- `endRfc3339` (`string`, optional): Optionally, the end time of the query in RFC3339 format or relative time (e.g. 'now') (defaults to now)
- `matcher` (`string`, optional): Optionally, a stream selector to narrow the search to matching streams (Loki: LogQL, e.g. '{namespace="prod"}'; VictoriaLogs: LogsQL). Defaults to searching across all streams.
- `startRfc3339` (`string`, optional): Optionally, the start time of the query in RFC3339 format or relative time (e.g. 'now-1h') (defaults to 1 hour ago)

Example input: `{"datasourceUid":"<datasourceUid>","labelName":"app"}`

### `grafanacloudmcp_list_oncall_schedules`

List OnCall schedules · Read-only

List Grafana OnCall schedules, optionally filtering by team ID. If a specific schedule ID is provided, retrieves details for only that schedule. Returns a list of schedule summaries including ID, name, team ID, timezone, and shift IDs. Supports pagination.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`integer`, optional): The page number to return (1-based)
- `scheduleId` (`string`, optional): The ID of the schedule to get details for. If provided, returns only that schedule's details
- `teamId` (`string`, optional): The ID of the team to list schedules for

Example input: `{}`

### `grafanacloudmcp_list_oncall_teams`

List OnCall teams · Read-only

List teams configured in Grafana OnCall. Returns a list of team objects with their details. Supports pagination.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`integer`, optional): The page number to return

Example input: `{}`

### `grafanacloudmcp_list_oncall_users`

List OnCall users · Read-only

List users from Grafana OnCall. These are OnCall users (separate from Grafana users). Can retrieve all users in the OnCall directory, a specific user by ID, or filter by username. Returns a list of user objects with their details. Supports pagination.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`integer`, optional): The page number to return
- `userId` (`string`, optional): The ID of the user to get details for. If provided, returns only that user's details
- `username` (`string`, optional): The username to filter users by. If provided, returns only the user matching this username

Example input: `{}`

### `grafanacloudmcp_list_prometheus_label_names`

List Prometheus label names · Read-only

List label names in a PromQL-compatible datasource (Prometheus, Thanos, Mimir, Cloud Monitoring, etc.). Allows filtering by series selectors and time range.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): The UID of the datasource to query
- `endRfc3339` (`string`, optional): Optionally, the end time of the time range to filter the results by. Supports RFC3339 or relative time (e.g. 'now')
- `limit` (`integer`, optional): Optionally, the maximum number of results to return. Default: `100`.
- `matches` (`array`, optional): Optionally, a list of label matchers to filter the results by
- `projectName` (`string`, optional): GCP project name to query (Cloud Monitoring datasources only). Overrides or substitutes the defaultProject configured on the datasource.
- `startRfc3339` (`string`, optional): Optionally, the start time of the time range to filter the results by. Supports RFC3339 or relative time (e.g. 'now-1h')

Example input: `{"datasourceUid":"<datasourceUid>"}`

### `grafanacloudmcp_list_prometheus_label_values`

List Prometheus label values · Read-only

Gets the values for a specific label name in a PromQL-compatible datasource (Prometheus, Thanos, Mimir, Cloud Monitoring, etc.). Allows filtering by series selectors and time range.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): The UID of the datasource to query
- `labelName` (`string`, required): The name of the label to query
- `endRfc3339` (`string`, optional): Optionally, the end time of the query. Supports RFC3339 or relative time (e.g. 'now')
- `limit` (`integer`, optional): Optionally, the maximum number of results to return. Default: `100`.
- `matches` (`array`, optional): Optionally, a list of selectors to filter the results by
- `projectName` (`string`, optional): GCP project name to query (Cloud Monitoring datasources only). Overrides or substitutes the defaultProject configured on the datasource.
- `startRfc3339` (`string`, optional): Optionally, the start time of the query. Supports RFC3339 or relative time (e.g. 'now-1h')

Example input: `{"datasourceUid":"<datasourceUid>","labelName":"app"}`

### `grafanacloudmcp_list_prometheus_metric_metadata`

List Prometheus metric metadata · Read-only

List Prometheus metric metadata. Returns metadata about metrics currently scraped from targets. Note: This endpoint is experimental.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): The UID of the datasource to query
- `limit` (`integer`, optional): The maximum number of metrics to return. Default: `10`.
- `limitPerMetric` (`integer`, optional): The maximum number of metrics to return per metric
- `metric` (`string`, optional): The metric to query
- `projectName` (`string`, optional): GCP project name to query (Cloud Monitoring datasources only). Overrides or substitutes the defaultProject configured on the datasource.

Example input: `{"datasourceUid":"<datasourceUid>"}`

### `grafanacloudmcp_list_prometheus_metric_names`

List Prometheus metric names · Read-only

Lists metric names in a PromQL-compatible datasource (Prometheus, Thanos, Mimir, Cloud Monitoring, etc.). Filters metric names using the provided regex. Supports pagination (page * limit must not exceed 10000) and an optional time range to restrict results to metrics active within that window. Cloud Monitoring ignores the time range.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): The UID of the datasource to query
- `endRfc3339` (`string`, optional): Optionally, the end time of the time range to filter the results by. Supports RFC3339 or relative time (e.g. 'now')
- `limit` (`integer`, optional): The maximum number of results to return. Default: `10`.
- `page` (`integer`, optional): The page number to return. Default: `1`.
- `projectName` (`string`, optional): GCP project name to query (Cloud Monitoring datasources only). Overrides or substitutes the defaultProject configured on the datasource.
- `regex` (`string`, optional): The regex to match against the metric names
- `startRfc3339` (`string`, optional): Optionally, the start time of the time range to filter the results by. Supports RFC3339 or relative time (e.g. 'now-1h')

Example input: `{"datasourceUid":"<datasourceUid>"}`

### `grafanacloudmcp_list_pyroscope_label_names`

List Pyroscope label names · Read-only

Lists all available label names (keys) found in profiles within a specified Pyroscope datasource, time range, and
optional label matchers. Label matchers are typically used to qualify a service name ({service_name="foo"}). Returns a
list of unique label strings (e.g., ["app", "env", "pod"]). Label names with double underscores (e.g. __name__) are
internal and rarely useful to users. If the time range is not provided, it defaults to the last hour.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `data_source_uid` (`string`, required): The UID of the datasource to query
- `end_rfc_3339` (`string`, optional): Optionally, the end time of the query in RFC3339 format or relative time (e.g. 'now') (defaults to now)
- `matchers` (`string`, optional): No description.
- `start_rfc_3339` (`string`, optional): Optionally, the start time of the query in RFC3339 format or relative time (e.g. 'now-1h') (defaults to 1 hour ago)

Example input: `{"data_source_uid":"<data_source_uid>"}`

### `grafanacloudmcp_list_pyroscope_label_values`

List Pyroscope label values · Read-only

Lists all available label values for a particular label name found in profiles within a specified Pyroscope datasource,
time range, and optional label matchers. Label matchers are typically used to qualify a service name ({service_name="foo"}).
Returns a list of unique label strings (e.g. for label name "env": ["dev", "staging", "prod"]). If the time range
is not provided, it defaults to the last hour.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `data_source_uid` (`string`, required): The UID of the datasource to query
- `name` (`string`, required): A label name
- `end_rfc_3339` (`string`, optional): Optionally, the end time of the query in RFC3339 format or relative time (e.g. 'now') (defaults to now)
- `matchers` (`string`, optional): Optionally, Prometheus style matchers used to filter the result set (defaults to: {})
- `start_rfc_3339` (`string`, optional): Optionally, the start time of the query in RFC3339 format or relative time (e.g. 'now-1h') (defaults to 1 hour ago)

Example input: `{"data_source_uid":"<data_source_uid>","name":"span.http.method"}`

### `grafanacloudmcp_list_pyroscope_profile_types`

List Pyroscope profile types · Read-only

Lists all available profile types available in a specified Pyroscope datasource and time range. Returns a list of all
available profile types (example profile type: "process_cpu:cpu:nanoseconds:cpu:nanoseconds"). A profile type has the
following structure: <name>:<sample type>:<sample unit>:<period type>:<period unit>. Not all profile types are available
for every service. If the time range is not provided, it defaults to the last hour.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `data_source_uid` (`string`, required): The UID of the datasource to query
- `end_rfc_3339` (`string`, optional): Optionally, the end time of the query in RFC3339 format or relative time (e.g. 'now') (defaults to now)
- `start_rfc_3339` (`string`, optional): Optionally, the start time of the query in RFC3339 format or relative time (e.g. 'now-1h') (defaults to 1 hour ago)

Example input: `{"data_source_uid":"<data_source_uid>"}`

### `grafanacloudmcp_list_snapshots`

List snapshots · Read-only

List Grafana dashboard snapshots with optional query and result limit filters.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `limit` (`integer`, optional): Maximum number of snapshots to return (Grafana defaults to 1000 when omitted)
- `query` (`string`, optional): Optional search query for snapshot name

Example input: `{}`

### `grafanacloudmcp_list_sql_databases`

List SQL databases · Read-only

List databases, schemas, or catalogs. Athena: omit catalog to list catalogs; set it to list databases. BigQuery: list datasets in database (project), defaulting to datasource config.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): UID of the SQL datasource.
- `catalog` (`string`, optional): Catalog name. For Athena: when empty returns catalogs; when set returns databases in that catalog.
- `database` (`string`, optional): Database name. For Snowflake: when set returns schemas in that database. For BigQuery: project to list datasets from; defaults to datasource config.
- `region` (`string`, optional): AWS region override (Athena).

Example input: `{"datasourceUid":"<datasourceUid>"}`

### `grafanacloudmcp_list_sql_tables`

List SQL tables · Read-only

List SQL tables and available metadata. BigQuery returns table/view names only; schema is the required dataset and database is the project.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): The UID of the SQL datasource.
- `catalog` (`string`, optional): Data catalog name (Athena only).
- `database` (`string`, optional): Database name to filter tables; BigQuery project (defaults to datasource defaultProject).
- `region` (`string`, optional): AWS region override (Athena only).
- `schema` (`string`, optional): Schema name to filter tables (Snowflake, PostgreSQL, MSSQL); required dataset for BigQuery.

Example input: `{"datasourceUid":"<datasourceUid>"}`

### `grafanacloudmcp_list_team_roles`

List team roles · Read-only

List all roles assigned to one or more teams. Returns a map of team IDs to their assigned roles.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `teamIds` (`array`, required): Team ID(s) to get roles for. Can be a single team or multiple teams.

Example input: `{"teamIds":[]}`

### `grafanacloudmcp_list_teams`

List teams · Read-only

Search for Grafana teams by a query string. Returns a list of matching teams with details like name, ID, and URL.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `query` (`string`, optional): The query to search for teams. Can be left empty to fetch all teams

Example input: `{}`

### `grafanacloudmcp_list_tempo_attribute_names`

List Tempo attribute names · Read-only

List available attribute names for TraceQL queries. Without a scope (resource, span, etc.) the response can be very large.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): UID of the tempo datasource to query
- `scope` (`string`, optional): Scope to filter attributes by (span, resource, event, link, instrumentation). Strongly recommended — omitting scope returns all attributes across all scopes which can be very large (100K+ chars).

Example input: `{"datasourceUid":"<datasourceUid>"}`

### `grafanacloudmcp_list_tempo_attribute_values`

List Tempo attribute values · Read-only

List values for a fully scoped attribute name (e.g. resource.service.name). Useful for discovering what values exist for a specific attribute.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): UID of the tempo datasource to query
- `name` (`string`, required): The attribute name to get values for (e.g. 'span.http.method', 'resource.service.name')
- `filter-query` (`string`, optional): Filter query to apply to the attribute values. It can only have one spanset and only &&'ed conditions like { <cond> && <cond> && ... }. This is useful for filtering the values to a specific set of values.

Example input: `{"datasourceUid":"<datasourceUid>","name":"span.http.method"}`

### `grafanacloudmcp_list_user_roles`

List user roles · Read-only

List all roles assigned to one or more users. Returns a map of user IDs to their assigned roles, excluding built-in roles and team-inherited roles.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `userIds` (`array`, required): User ID(s) to get roles for. Can be a single user or multiple users.

Example input: `{"userIds":[]}`

### `grafanacloudmcp_list_users_by_org`

List users by org · Read-only

List users in the Grafana organization, optionally filtered by a search query. Results are paginated; the response includes totalCount, page and perPage alongside organization users with details like userid, email, role etc.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `limit` (`integer`, optional): Maximum number of users to return (max 1000). Default: `100`.
- `page` (`integer`, optional): Page number for pagination (1-indexed). Default: `1`.
- `query` (`string`, optional): Optional search string matched against login, email and name

Example input: `{}`

### `grafanacloudmcp_query_cloudwatch`

Query CloudWatch · Read-only

Query AWS CloudWatch metrics via Grafana. Requires region.

Time formats: 'now-1h', '2026-02-02T19:00:00Z', '1738519200000' (Unix ms)

Common namespaces: AWS/EC2, AWS/ECS, AWS/RDS, AWS/Lambda, ECS/ContainerInsights

Example dimensions: ECS: {ClusterName, ServiceName}, EC2: {InstanceId}

Cross-account monitoring: Use accountId to query metrics from a specific source account (e.g. '123456789012') or 'all' to query all linked accounts. Only applicable when using a CloudWatch monitoring account datasource.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): The UID of the CloudWatch datasource to query.
- `metricName` (`string`, required): Metric name (e.g. CPUUtilization, MemoryUtilization, Invocations)
- `namespace` (`string`, required): CloudWatch namespace (e.g. AWS/ECS, AWS/EC2, AWS/RDS, AWS/Lambda)
- `region` (`string`, required): AWS region (e.g. us-east-1)
- `accountId` (`string`, optional): AWS account ID for cross-account monitoring. Specify an account ID to query metrics from a specific source account, or 'all' to query all accounts the monitoring account is permitted to query. Only relevant when using a CloudWatch monitoring account datasource.
- `dimensions` (`object`, optional): Dimensions as key-value pairs (e.g. {"ClusterName": "my-cluster"})
- `end` (`string`, optional): End time. Formats: 'now', '2026-02-02T20:00:00Z', '1738522800000' (Unix ms). Default: now
- `period` (`integer`, optional): Period in seconds (default: 300)
- `start` (`string`, optional): Start time. Formats: 'now-1h', '2026-02-02T19:00:00Z', '1738519200000' (Unix ms). Default: now-1h
- `statistic` (`string`, optional): Statistic type: Average, Sum, Maximum, Minimum, SampleCount, or a percentile such as p50, p95 or p99.9. Default: Average

Example input: `{"datasourceUid":"<datasourceUid>","metricName":"<metricName>","namespace":"<namespace>","region":"<region>"}`

### `grafanacloudmcp_query_cloudwatch_logs`

Query CloudWatch Logs · Read-only

Run a CloudWatch Logs Insights query against one or more log groups via Grafana and return the result rows. Requires region. Waits up to 30s for the query to complete. Rows are returned in ascending time order.

Query examples:
- fields @timestamp, @message | sort @timestamp desc | limit 20
- filter @message like /error/i | stats count() by bin(5m)

Time formats: 'now-1h', '2026-02-02T19:00:00Z', '1738519200000' (Unix ms)

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): The UID of the CloudWatch datasource to query.
- `logGroups` (`array`, required): Log groups to query: either all names (e.g. ["/aws/lambda/my-function"]) or all ARNs. ARNs are required for log groups in linked source accounts when querying from a monitoring account.
- `queryString` (`string`, required): CloudWatch Logs Insights query (e.g. 'fields @timestamp, @message | filter @message like /ERROR/ | sort @timestamp desc | limit 20')
- `region` (`string`, required): AWS region (e.g. us-east-1)
- `end` (`string`, optional): End time. Formats: 'now', '2026-02-02T20:00:00Z', '1738522800000' (Unix ms). Default: now
- `limit` (`integer`, optional): Maximum number of rows to return (default: 100, max: 1000)
- `start` (`string`, optional): Start time. Formats: 'now-1h', '2026-02-02T19:00:00Z', '1738519200000' (Unix ms). Default: now-1h

Example input: `{"datasourceUid":"<datasourceUid>","logGroups":[],"queryString":"fields @timestamp, @message | filter @message like /ERROR/ | sort @timestamp desc | limit 20","region":"<region>"}`

### `grafanacloudmcp_query_elasticsearch`

Query Elasticsearch · Read-only

Executes a search query against an Elasticsearch or OpenSearch datasource and retrieves matching documents. Supports Lucene query syntax (e.g., 'status:200 AND host:server1') for both Elasticsearch and OpenSearch. Elasticsearch Query DSL JSON is also supported for Elasticsearch datasources only (not OpenSearch). Returns a list of documents with their index, ID, source fields, and optional score. Use this to search logs, metrics, or any indexed data stored in Elasticsearch or OpenSearch. Defaults to 10 results and sorts by @timestamp in descending order (newest first).

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): The UID of the Elasticsearch or OpenSearch datasource to query
- `index` (`string`, required): The index pattern to search (e.g., 'logs-*', 'filebeat-*', or a specific index name)
- `query` (`string`, required): The search query. For Elasticsearch datasources, this can be either Lucene query syntax (e.g., 'status:200 AND host:server1') or Elasticsearch Query DSL JSON (for advanced queries with aggregations). For OpenSearch datasources, only Lucene query syntax is supported.
- `endTime` (`string`, optional): Optionally, the end time. Filters results to documents with the configured time field (default @timestamp) <= this value. Supports RFC3339 (e.g. '2024-01-01T23:59:59Z'), relative to now (e.g. 'now', 'now-1h'), or Unix timestamps
- `limit` (`integer`, optional): Optionally, the maximum number of documents to return (max: 100, default: 10). Default: `10`.
- `startTime` (`string`, optional): Optionally, the start time. Filters results to documents with the configured time field (default @timestamp) >= this value. Supports RFC3339 (e.g. '2024-01-01T00:00:00Z'), relative to now (e.g. 'now', 'now-1h', 'now-30m'), or Unix timestamps

Example input: `{"datasourceUid":"<datasourceUid>","index":"logs-*","query":"status:200 AND host:server1"}`

### `grafanacloudmcp_query_graphite`

Query Graphite metrics · Read-only

Executes a Graphite render API query against a Graphite datasource and returns matching metric series with their datapoints. Supports the full Graphite target expression language including wildcard patterns (e.g. 'servers.web*.cpu.load5'), aggregation functions (e.g. 'sumSeries(app.*.requests)'), and tag-based queries (e.g. 'seriesByTag(\'name=cpu.load\')'). Datapoints with no recorded value are returned with a null value field. Time range defaults to the last hour if not specified.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): The UID of the Graphite datasource to query
- `target` (`string`, required): The Graphite target expression to evaluate (e.g. 'servers.web*.cpu.load5', 'sumSeries(app.*.requests)', 'seriesByTag(\'name=cpu.load\')')
- `from` (`string`, optional): Start of the time range. Accepts RFC3339 (e.g. '2024-01-01T00:00:00Z'), Unix seconds, or relative times (e.g. '-1h', '-24h', 'now-1h'). Defaults to '-1h'.
- `maxDataPoints` (`integer`, optional): Optional maximum number of data points per series. Graphite consolidates data when the requested range exceeds this value. Defaults to returning the stored resolution.
- `until` (`string`, optional): End of the time range. Accepts RFC3339, Unix seconds, or relative times (e.g. 'now'). Defaults to 'now'.

Example input: `{"datasourceUid":"<datasourceUid>","target":"servers.web*.cpu.load5"}`

### `grafanacloudmcp_query_graphite_density`

Query Graphite metric density · Read-only

Analyses metric data density for one or more Graphite series over a time window. Returns per-series statistics: fillRatio (fraction of non-null datapoints, 0.0–1.0), totalPoints, nonNullPoints, lastSeen (Unix timestamp of most recent non-null value, or null if none), longestGap (longest consecutive null run in seconds), and estimatedInterval (inferred write interval in seconds). Supports wildcard targets (e.g. 'obox-cl*.sys.sessions') to diagnose stale, sparse, or dead metrics across a cluster. A fillRatio of 0 with lastSeen null means the series reported no data in the requested window.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): The UID of the Graphite datasource to query
- `target` (`string`, required): Graphite target expression; supports wildcards (e.g. 'obox-cl*.sys.sessions')
- `from` (`string`, optional): Start of the time range. Accepts RFC3339, Unix seconds, or relative times (e.g. '-1h', 'now-1h'). Defaults to '-1h'.
- `until` (`string`, optional): End of the time range. Accepts RFC3339, Unix seconds, or relative times (e.g. 'now'). Defaults to 'now'.

Example input: `{"datasourceUid":"<datasourceUid>","target":"obox-cl*.sys.sessions"}`

### `grafanacloudmcp_query_loki_logs`

Query Loki logs · Read-only

Executes a log query against a Loki or VictoriaLogs datasource and returns matching log entries (or metric samples on Loki). Defaults to the last hour, a limit of 10 entries, and 'backward' direction (newest first). The `logql` parameter takes LogQL on Loki and LogsQL on VictoriaLogs (e.g., Loki: `{app="foo"} |= "error"`; VictoriaLogs: `{app="foo"} "error"`). To count matching log lines precisely, use a `count_over_time()` metric query with queryType='instant'. For broad queries that match many lines, set `format` to 'compact' to group results by stream and avoid repeating label metadata on every line. Query cost is the bytes scanned, which the index statistics for the stream selector over the same time range estimate before a broad selector or long time range is run. If this server enables the Loki cost guardrail, expensive queries are rejected before execution: query cost is bytes SCANNED, determined only by the stream selector and time range — line filters (|=) and parsers (| json) reduce what is returned, not what is scanned. Use a stream selector with at least one selective positive label matcher (never `{}`, `=~".*"`/`=~".+"`, or negative-only matchers), keep time ranges narrow; rejected queries return rewrite guidance.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): The UID of the datasource to query
- `logql` (`string`, required): The LogQL query to execute against Loki. This can be a simple label matcher or a complex query with filters, parsers, and expressions. Supports full LogQL syntax including label matchers, filter operators, pattern expressions, and pipeline operations.
- `direction` (`string`, optional): Optionally, the direction of the query: 'forward' (oldest first) or 'backward' (newest first, default)
- `endRfc3339` (`string`, optional): Optionally, the end time of the query in RFC3339 format or relative time (e.g. 'now')
- `format` (`string`, optional): Output format for log (streams) queries: 'full' (default) returns every entry with its own label metadata; 'compact' groups lines by stream so each label set is emitted only once, substantially reducing response size for broad queries. Structured metadata keys that are constant within a stream appear once on the stream header; keys that vary across lines appear per-line. Ignored for metric queries. One of: `full`, `compact`.
- `limit` (`integer`, optional): Optionally, the maximum number of log lines to return (default max: 100, configurable by MCP server). Default: `10`.
- `queryType` (`string`, optional): Query type: 'range' (default) or 'instant'. Instant queries return a single value at one point in time. Range queries return values over a time window. Use 'instant' for metric queries when you want the current value.
- `startRfc3339` (`string`, optional): Optionally, the start time of the query in RFC3339 format or relative time (e.g. 'now-1h')
- `stepSeconds` (`integer`, optional): Resolution step in seconds for range metric queries. When running metric queries with queryType='range', this controls the time resolution of the returned data points.

Example input: `{"datasourceUid":"<datasourceUid>","logql":"<logql>"}`

### `grafanacloudmcp_query_loki_patterns`

Query Loki patterns · Read-only

Retrieves detected log patterns from a Loki datasource for a given stream selector and time range. Returns a list of patterns, each containing a pattern string, a total count of occurrences, and a detected `level` when available. Patterns help identify common log structures and anomalies. The `logql` parameter must be a stream selector (e.g., `{job="nginx"}`) and does not support line filters or aggregations. Defaults to the last hour if the time range is omitted. **Not supported on VictoriaLogs** datasources - use a `| stats` pipeline instead.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): The UID of the datasource to query
- `logql` (`string`, required): A LogQL stream selector to identify the logs to analyze for patterns (e.g. {job="foo", namespace="bar"})
- `endRfc3339` (`string`, optional): Optionally, the end time of the query in RFC3339 format or relative time (e.g. 'now') (defaults to now)
- `startRfc3339` (`string`, optional): Optionally, the start time of the query in RFC3339 format or relative time (e.g. 'now-1h') (defaults to 1 hour ago)
- `step` (`string`, optional): Optionally, the query resolution step (e.g. '5m')

Example input: `{"datasourceUid":"<datasourceUid>","logql":"<logql>"}`

### `grafanacloudmcp_query_loki_stats`

Get Loki log statistics · Read-only

Retrieves index-level statistics about log streams matching a given selector within a Loki or VictoriaLogs datasource and time range. Returns an object containing the count of streams, chunks, entries, and total bytes (e.g., `{"streams": 5, "chunks": 50, "entries": 10000, "bytes": 512000}`). **Important**: the `entries` count reflects storage-level index entries (chunk metadata), NOT the number of individual log lines matching the selector. Counting actual matching log lines requires a `count_over_time()` LogQL metric query. On VictoriaLogs only `entries` is populated; the other fields remain zero. The `logql` parameter **must** be a simple label selector (e.g., `{app="nginx", env="prod"}`) and does not support line filters, parsers, or aggregations. The `bytes` field estimates how much data a log query over the same selector and time range would scan, which is useful to know before running a broad selector or long time range. Defaults to the last hour if the time range is omitted.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): The UID of the datasource to query
- `logql` (`string`, required): The LogQL matcher expression to execute. This parameter only accepts label matcher expressions and does not support full LogQL queries. Line filters, pattern operations, and metric aggregations are not supported by the stats API endpoint. Only simple label selectors can be used here.
- `endRfc3339` (`string`, optional): Optionally, the end time of the query in RFC3339 format or relative time (e.g. 'now')
- `startRfc3339` (`string`, optional): Optionally, the start time of the query in RFC3339 format or relative time (e.g. 'now-1h')

Example input: `{"datasourceUid":"<datasourceUid>","logql":"<logql>"}`

### `grafanacloudmcp_query_prometheus`

Query Prometheus metrics · Read-only

Query a PromQL-compatible datasource (Prometheus, Thanos, Mimir, Cloud Monitoring, etc.) using a PromQL expression. Returns data without opening a chart. Supports instant and range queries. Time: RFC3339 or relative expressions like 'now', 'now-1h'.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): The UID of the datasource to query
- `endTime` (`string`, required): The end time. Supported formats are RFC3339 or relative to now (e.g. 'now', 'now-1.5h', 'now-2h45m'). Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h', 'd'.
- `expr` (`string`, required): The PromQL expression to query
- `projectName` (`string`, optional): GCP project name to query (Cloud Monitoring datasources only). Overrides or substitutes the defaultProject configured on the datasource.
- `queryType` (`string`, optional): The type of query to use. Either 'range' or 'instant'
- `startTime` (`string`, optional): The start time. Required if queryType is 'range', ignored if queryType is 'instant' Supported formats are RFC3339 or relative to now (e.g. 'now', 'now-1.5h', 'now-2h45m'). Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h', 'd'.
- `stepSeconds` (`integer`, optional): The time series step size in seconds. Required if queryType is 'range', ignored if queryType is 'instant'

Example input: `{"datasourceUid":"<datasourceUid>","endTime":"now","expr":"<expr>"}`

### `grafanacloudmcp_query_prometheus_histogram`

Query Prometheus histogram percentile · Read-only

Query Prometheus histogram percentiles from classic histogram '_bucket' series.

Generates histogram_quantile PromQL. Example: metric='http_duration', percentile=95, labels='job="api"'

Time formats: 'now-1h', '2026-02-02T19:00:00Z', '1738519200000' (Unix ms)

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): The UID of the Prometheus datasource
- `metric` (`string`, required): Base histogram metric name (without _bucket suffix)
- `percentile` (`number`, required): Percentile to calculate (e.g. 50, 90, 95, 99)
- `endTime` (`string`, optional): End time (default: now). Supports RFC3339, relative, or Unix ms.
- `labels` (`string`, optional): Label selector (e.g. job="api", service="gateway")
- `projectName` (`string`, optional): GCP project name to query (Cloud Monitoring datasources only). Overrides or substitutes the defaultProject configured on the datasource.
- `rateInterval` (`string`, optional): Rate interval for the query (default: 5m)
- `startTime` (`string`, optional): Start time (default: now-1h). Supports RFC3339, relative (now-1h), or Unix ms.
- `stepSeconds` (`integer`, optional): Step size in seconds for range query (default: 60)

Example input: `{"datasourceUid":"<datasourceUid>","metric":"<metric>","percentile":50}`

### `grafanacloudmcp_query_pyroscope`

Query Pyroscope · Read-only

Unified Pyroscope query tool for fetching profiles or metrics from Pyroscope. Profile data shows WHICH functions consume resources; metrics data
shows WHEN consumption spiked. Use query_type="both" for complete analysis in one call.

query_type options (extends Grafana's PyroscopeQueryType):
- "profile": returns profile data (shape controlled by format)
- "metrics": returns time-series data points; for cumulative profile types (e.g. CPU time, allocations) each point is a
  per-second rate over its step, in the reported unit (e.g. "cores" for CPU time)
- "both" (default): returns both profile and metrics in one response

format options (shape of the profile data):
- "table" (default): per-function table with flat (self) and cumulative values, ranked by flat
- "dot": call graph in Graphviz DOT format; nodes are per source line, so one function may span several nodes

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `data_source_uid` (`string`, required): The UID of the datasource to query
- `profile_type` (`string`, required): The profile type (e.g. process_cpu:cpu:nanoseconds:cpu:nanoseconds)
- `end_rfc_3339` (`string`, optional): End time in RFC3339 or relative time (e.g. 'now') (defaults to now)
- `format` (`string`, optional): Profile output format: "table" (default) for a per-function flat/cum table, or "dot" for a call graph in Graphviz DOT format
- `group_by` (`array`, optional): Labels to group metrics series by
- `matchers` (`string`, optional): Prometheus style matchers (defaults to: {})
- `max_node_depth` (`integer`, optional): Max functions in the profile table or nodes in the call graph; it is a count, not a depth (default: 100)
- `query_type` (`string`, optional): Query type: "profile" (flamegraph), "metrics" (time-series), or "both" (default). Use "both" for complete analysis
- `start_rfc_3339` (`string`, optional): Start time in RFC3339 or relative time (e.g. 'now-1h') (defaults to 1 hour ago)
- `step` (`number`, optional): Seconds between metrics data points (default: auto)

Example input: `{"data_source_uid":"<data_source_uid>","profile_type":"<profile_type>"}`

### `grafanacloudmcp_query_quickwit`

Query Quickwit · Read-only

Executes a search query against a Quickwit datasource and retrieves matching documents. Supports Lucene query syntax (e.g., 'severity_text:ERROR AND service_name:api') and partial Elasticsearch-compatible Query DSL JSON. The timestamp field is resolved from Quickwit index metadata (not jsonData.timeField). Returns a list of documents with their index, ID, source fields, and optional score. Use this to search logs or other indexed data stored in Quickwit. Defaults to 10 results and sorts by the index timestamp field in descending order (newest first).

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): The UID of the Quickwit datasource to query
- `query` (`string`, required): The search query in Lucene syntax (e.g., 'severity_text:ERROR AND service_name:api') or partial Elasticsearch-compatible Query DSL JSON
- `endTime` (`string`, optional): Optionally, the end time. Filters results to documents with timestamp <= this value. Supports RFC3339 (e.g. '2024-01-01T23:59:59Z'), relative to now (e.g. 'now', 'now-1h'), or Unix timestamps
- `index` (`string`, optional): Optionally, the index or index pattern to search. Defaults to the index configured on the datasource (jsonData.index)
- `limit` (`integer`, optional): Optionally, the maximum number of documents to return (max: 100, default: 10). Default: `10`.
- `startTime` (`string`, optional): Optionally, the start time. Filters results to documents with timestamp >= this value. Supports RFC3339 (e.g. '2024-01-01T00:00:00Z'), relative to now (e.g. 'now', 'now-1h', 'now-30m'), or Unix timestamps

Example input: `{"datasourceUid":"<datasourceUid>","query":"severity_text:ERROR AND service_name:api"}`

### `grafanacloudmcp_query_tempo_metrics`

Query Tempo metrics · Read-only

Compute trace-derived metrics using a TraceQL metrics query. The syntax is unlike PromQL. Use type 'instant' for a single value or 'range' for a time series (default). Instant queries over large time ranges may timeout — keep the window under 15 minutes for instant, or use range instead. Returns each series with its labels and either its samples and exemplars (range) or a single value (instant).

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): UID of the tempo datasource to query
- `query` (`string`, required): TraceQL metrics query of the form '{ <selector> } | <aggregation> [by (<attribute>)]'. Example: '{ } | quantile_over_time(span:duration, .99) by (span.name)'.
- `end` (`string`, optional): End time (RFC3339 format). If not provided will search the past 1 hour.
- `start` (`string`, optional): Start time (RFC3339 format). If not provided will search the past 1 hour.
- `type` (`string`, optional): Query type: 'instant' returns a single value at the end of the time range; 'range' returns a time series. Default is 'range'. One of: `instant`, `range`. Default: `range`.

Example input: `{"datasourceUid":"<datasourceUid>","query":"{ } | quantile_over_time(span:duration, .99) by (span.name)"}`

### `grafanacloudmcp_render_alert_creation`

Create an alert draft · Read-only

Open an interactive draft for a Grafana-managed Prometheus alert. Supply the actual datasource UID, valid PromQL expression, title, threshold in query units, and unit (s, ms, percent, bytes, short). The user edits and explicitly creates the rule in the app. Requires a Prometheus datasource and an existing folder for the final create. Uses a dedicated 1m evaluation group; never creates on render. History is metric context, not an alert simulation. Supply exactly one draft.baseMetric: the actual Prometheus metric name the expression is built on (never a label, function or invented name; use the selected metric supplied by the app or verify it with available metric discovery tools). When the user changes the metric, keep the existing draft's non-query configuration and ruleUid, and regenerate the expression, title, unit and threshold to suit the new metric. If the request supplied a proposalRequestId, pass the same proposalRequestId unchanged; it is echoed in the result to correlate a pending proposal replacement.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `draft` (`object`, required): No description.
- `proposalRequestId` (`string`, optional): Echo the proposalRequestId from the request, if any, unchanged.
- `timeRange` (`string`, optional): Metric history window; defaults to 14d. History is metric context, not an alert simulation. One of: `24h`, `7d`, `14d`, `30d`.

Example input: `{"draft":{}}`

### `grafanacloudmcp_render_alert_status`

Display alert status · Read-only

Display read-only Grafana-managed alert rule status, current instances, 14-day state history, silence state and real query samples for an exact rule UID. Query samples are shown only for simple Prometheus scalar-threshold rules.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `rule_uid` (`string`, required): Exact UID of a Grafana-managed alert rule readable by the caller.
- `time_range` (`string`, optional): Query chart window. Defaults to 6h. State history always spans 14 days. One of: `1h`, `6h`, `24h`, `7d`.

Example input: `{"rule_uid":"<rule_uid>"}`

### `grafanacloudmcp_resolve_alert_creation`

Check alert creation status · Read-only

Read the saved definition for a previously submitted alert draft. Never repeats the write; missing or conflicting definitions leave the outcome uncertain.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `draft` (`object`, required): No description.

Example input: `{"draft":{}}`

### `grafanacloudmcp_run_panel_query`

Run panel query · Read-only

Executes one or more dashboard panel queries with optional time range and variable overrides. Accepts an array of panel IDs to query in a single call. Fetches the dashboard, extracts queries from the specified panels, substitutes template variables and Grafana macros ($__range, $__rate_interval, $__interval, $__auto), resolves the "default" datasource reference, and routes to the appropriate datasource (Prometheus, Loki, ClickHouse, CloudWatch, InfluxDB, BigQuery, MSSQL, PostgreSQL, Neo4j, or Infinity with a backend parser). Returns results keyed by panel ID - partial failures are allowed (some panels can succeed while others fail). If a panel uses a template variable datasource you cannot access, provide datasourceUid and datasourceType to override.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `dashboardUid` (`string`, required): Dashboard UID
- `panelIds` (`array`, required): Panel IDs to execute (one or more)
- `datasourceType` (`string`, optional): Fallback datasource type used only when the datasource cannot be read (prometheus, loki, grafana-clickhouse-datasource, cloudwatch, influxdb, grafana-bigquery-datasource, mssql, grafana-postgresql-datasource, postgres). When the datasource is readable its real type is used and this is ignored.
- `datasourceUid` (`string`, optional): Override datasource UID
- `end` (`string`, optional): Override end time (e.g. 'now', RFC3339, Unix ms)
- `queryIndex` (`integer`, optional): Index of the query to execute per panel (0-based, defaults to 0).
- `start` (`string`, optional): Override start time (e.g. 'now-1h', RFC3339, Unix ms)
- `variables` (`object`, optional): Override dashboard variables (e.g. {"job": "api-server"})

Example input: `{"dashboardUid":"<dashboardUid>","panelIds":[]}`

### `grafanacloudmcp_search_alert_creation_metrics`

Search alert metrics · Read-only

Search metric names on a Prometheus datasource by case-insensitive substring, using the caller's Grafana access. Returns at most 50 names and whether more exist; names come only from the datasource.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): Datasource Uid
- `search` (`string`, required): Search

Example input: `{"datasourceUid":"<datasourceUid>","search":"<search>"}`

### `grafanacloudmcp_search_dashboards`

Search dashboards · Read-only

Search Grafana dashboards by query and/or folderUid, folderPath, tag, and starred. Returns matching dashboards with title, UID, folder, folder path, tags, and URL.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `folderPath` (`string`, optional): Optional folder path like Ops/Production. Includes subfolders. Case-insensitive
- `folderUid` (`string`, optional): Optional immediate folder UID (not nested)
- `limit` (`integer`, optional): Maximum number of results to return (max 100). Default: `50`.
- `page` (`integer`, optional): Page number for pagination (1-indexed). Default: `1`.
- `query` (`string`, optional): Optional query. Omit to filter by folderUid, folderPath, tag, or starred
- `starred` (`boolean`, optional): If true, only starred dashboards
- `tag` (`array`, optional): Optional tags to match (AND)

Example input: `{}`

### `grafanacloudmcp_search_docs`

Search Docs · Read-only

Search Grafana documentation. Returns matching pages with title, URL, description, and product. Call with no query to list available product groups.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `limit` (`integer`, optional): Maximum results to return (default 5)
- `product` (`string`, optional): Filter results to a specific product (e.g. 'Grafana Tempo', 'Grafana Loki')
- `query` (`string`, optional): Search query for Grafana documentation. Omit to list all available product groups.

Example input: `{}`

### `grafanacloudmcp_search_folders`

Search folders · Read-only

Search for Grafana folders by a query string. Returns matching folders with details like title, UID, and URL.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `query` (`string`, optional): The query to search for

Example input: `{}`

### `grafanacloudmcp_search_plugin_information`

Search plugins · Read-only

Search the Grafana plugin catalog by keyword, purpose, or partial name (e.g. 'azure monitoring', 'loki', 'database'). Returns results sorted by trust: official Grafana Labs plugins first, then commercial partner plugins, then community plugins, each with its exact pluginId. Results include warnings for enterprise-only or Angular-based plugins.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `query` (`string`, required): Keyword to search for plugins (e.g. 'azure', 'prometheus', 'loki', 'database'). Matches against plugin name, slug, description, and keywords.

Example input: `{"query":"azure"}`

### `grafanacloudmcp_search_tempo_traces`

Search Tempo traces · Read-only

Search for traces using TraceQL queries. Returns each matching trace with its root service, root span name, start time and duration, and the span sets the query matched. Each span lists its ID, start time, duration and the attributes the query returned, as an object mapping attribute names to values.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `datasourceUid` (`string`, required): UID of the tempo datasource to query
- `query` (`string`, required): TraceQL query string
- `end` (`string`, optional): End time for the search (RFC3339 format). If not provided will search the past 1 hour. If provided, must be after start.
- `limit` (`integer`, optional): Maximum number of traces to return. Default: `20`.
- `spss` (`integer`, optional): Maximum number of matching spans to return per span set. Default: `3`.
- `start` (`string`, optional): Start time for the search (RFC3339 format). If not provided will search the past 1 hour. If provided, must be before end.

Example input: `{"datasourceUid":"<datasourceUid>","query":"*"}`

### `grafanacloudmcp_simulate_alert_creation`

Simulate alert rule · Read-only

Simulate the current draft on Grafana without saving. Requires a write-enabled connection because Grafana requires rule-create or rule-write permission for backtesting. The editor does not invoke this tool or display simulation results. Client requests are limited to 1440 evaluations and the stack's own cap; unavailable or incomplete results never report a firing count.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `draft` (`object`, required): No description.
- `fromMs` (`integer`, required): No description.
- `toMs` (`integer`, required): No description.

Example input: `{"draft":{},"fromMs":1,"toMs":1}`

### `grafanacloudmcp_suggest_loki_alloy_label_config`

Suggest Alloy label enforcement config · Read-only

Generates an Alloy loki.process snippet enforcing an approved label set via stage.label_keep, with optional log-level normalisation and soft-enforcement placeholders.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `approvedLabels` (`array`, required): Labels to keep on the index.
- `componentName` (`string`, optional): No description.
- `forwardTo` (`string`, optional): No description.
- `normalizeLogLevel` (`boolean`, optional): No description.
- `requiredLabels` (`array`, optional): Labels that get an 'unknown' placeholder when missing.

Example input: `{"approvedLabels":[]}`

### `grafanacloudmcp_user_info`

Get current user info · Read-only

Get information about the current Grafana identity: login, email, name, whether it is a Grafana (server) admin, the current organization, and the organizations it can access (with roles). Call this to discover which orgId values are valid before targeting a specific organization, and to understand the identity's capabilities.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `grafanacloudmcp_wait_for_investigation`

Wait for investigation · Read-only

Wait for a Grafana Assistant investigation (AI-driven root-cause investigation) to settle, up to timeoutSeconds (default 45, max 300). Many MCP clients cancel tool calls after 60 seconds.

Returns as soon as the investigation is settled — completed, failed, cancelled, or paused — or when the timeout elapses, whichever is first. The result is a compact status: state, settled, timedOut, title, summary, completion quality, failure details, and a url to open the investigation in Grafana.

Investigations usually take several minutes, so settled is often false on return. A paused investigation is waiting for a person in Grafana and will not progress on its own.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `investigationId` (`string`, required): Investigation ID.
- `timeoutSeconds` (`integer`, optional): Optional. Maximum seconds to wait, from 1 to 300. Defaults to 45. Many MCP clients cancel tool calls after 60 seconds.

Example input: `{"investigationId":"<investigationId>"}`

### `grafanacloudmcp_add_activity_to_incident`

Add activity to incident · Write

Add a note (userNote activity) to an existing incident's timeline using its ID. The note body can include URLs which will be attached as context. Use this to add context to an incident.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `body` (`string`, required): The body of the activity. URLs will be parsed and attached as context
- `incidentId` (`string`, required): The ID of the incident to add the activity to
- `eventTime` (`string`, optional): The time that the activity occurred. If not provided, the current time will be used

Example input: `{"body":"<body>","incidentId":"<incidentId>"}`

### `grafanacloudmcp_alerting_routing_write`

Write alerting routing · Write

Create Grafana-managed contact points for alert notifications using operation 'create_contact_point'.
Requires name, type and integration-specific settings. Returns uid, name and type without settings or secrets.
Grafana-managed is the default and remains editable in the UI. Use managed_by='datasource' for an external Mimir/Cortex Alertmanager receiver when requested or when established conversation or environment context clearly identifies an external Alertmanager workflow. An external query datasource or an empty Grafana contact point list alone is insufficient. Ask if context conflicts.
Use native Alertmanager settings (email: to, webhook: url). Without datasource_uid select the sole compatible datasource, or return candidates for selection if ambiguous. Does not change notification routes.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Contact point name. Integrations with the same name are grouped together.
- `operation` (`string`, required): The operation to perform: 'create_contact_point'. One of: `create_contact_point`.
- `settings` (`object`, required): Integration-specific settings as a JSON object (for example {"addresses":"team@example.com"} for email).
- `type` (`string`, required): Integration type (for example email, slack or webhook).
- `datasource_uid` (`string`, optional): External Mimir/Cortex Alertmanager UID. Only for managed_by=datasource. Omit to select the sole compatible datasource. Ambiguity returns candidates for selection.
- `disable_provenance` (`boolean`, optional): Keep the contact point editable in the Grafana UI. Defaults to true.
- `disable_resolve_message` (`boolean`, optional): Disable resolved notifications. Defaults to false.
- `managed_by` (`string`, optional): Creation target. Omission defaults to Grafana-managed. Select datasource when requested or clearly established by conversation or environment context. One of: `grafana`, `datasource`. Default: `grafana`.
- `uid` (`string`, optional): Optional integration UID. Grafana generates one if omitted.

Example input: `{"name":"span.http.method","operation":"create_contact_point","settings":{},"type":"<type>"}`

### `grafanacloudmcp_create_annotation`

Create Annotation · Write

Create a new annotation on a dashboard or panel. Set format to 'graphite' and provide 'what' for Graphite-format annotations.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `dashboardUid` (`string`, optional): Dashboard UID
- `data` (`object`, optional): Optional JSON payload
- `format` (`string`, optional): Set to 'graphite' to create a Graphite-format annotation. One of: `graphite`.
- `graphiteData` (`string`, optional): Optional string payload for Graphite format
- `panelId` (`integer`, optional): Panel ID
- `tags` (`array`, optional): Optional list of tags
- `text` (`string`, optional): Annotation text (required unless format is graphite)
- `time` (`integer`, optional): Start time epoch ms
- `timeEnd` (`integer`, optional): End time epoch ms
- `what` (`string`, optional): Annotation text for Graphite format (required when format is graphite)
- `when` (`integer`, optional): Epoch ms timestamp for Graphite format

Example input: `{}`

### `grafanacloudmcp_create_datasource`

Create datasource · Write

Create a datasource in two steps. Called with only the type, it returns the plugin's field schema and creates nothing. Called with the type, the display name in the top-level name argument, schemaReviewed=true, and field values in the fields map, it creates the datasource. The plugin for the type must already be installed. Secrets (passwords, tokens) are not accepted. Returns UID, health check, and a config page link.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Datasource display name
- `type` (`string`, required): Grafana datasource plugin type, for example prometheus
- `access` (`string`, optional): How Grafana should access the datasource (proxy or direct)
- `basicAuth` (`boolean`, optional): Whether Grafana should use basic auth
- `database` (`string`, optional): Optional database name
- `fields` (`object`, optional): Datasource field values to provision, keyed by field key from the schema returned on the first call. The server uses each field's target (root or jsonData) to place values correctly in the YAML. Example: {"url": "http://prometheus:9090", "httpMethod": "POST"}.
- `isDefault` (`boolean`, optional): Whether this should become the default datasource
- `schemaReviewed` (`boolean`, optional): True once the field schema has been retrieved; required to create a schema-backed datasource.
- `url` (`string`, optional): Datasource base URL when required by the plugin
- `withCredentials` (`boolean`, optional): Whether Grafana should forward credentials such as cookies

Example input: `{"name":"span.http.method","type":"<type>"}`

### `grafanacloudmcp_create_folder`

Create folder · Write

Create a Grafana folder. Provide a title and optional UID. Returns the created folder.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `title` (`string`, required): The title of the folder.
- `parentUid` (`string`, optional): Optional parent folder UID. If set, the folder will be created under this parent.
- `uid` (`string`, optional): Optional folder UID. If omitted, Grafana will generate one.

Example input: `{"title":"<title>"}`

### `grafanacloudmcp_create_incident`

Create incident · Write

Create a new Grafana incident. Requires title, severity, and room prefix. Allows setting status, labels and custom fields. Creating an incident may notify or page many people.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `roomPrefix` (`string`, required): The prefix of the room to create the incident in
- `severity` (`string`, required): The severity of the incident
- `title` (`string`, required): The title of the incident
- `attachCaption` (`string`, optional): The caption of the attachment
- `attachUrl` (`string`, optional): The URL of the attachment
- `customFields` (`array`, optional): Custom field values to set on the new incident
- `isDrill` (`boolean`, optional): Whether the incident is a drill incident
- `labels` (`array`, optional): The labels to add to the incident
- `status` (`string`, optional): The status of the incident

Example input: `{"roomPrefix":"<roomPrefix>","severity":"minor","title":"<title>"}`

### `grafanacloudmcp_create_investigation`

Create Assistant Investigation · Write

Start a Grafana Assistant investigation: an agentic, multi-step root-cause analysis across the stack's metrics, logs, traces, dashboards, and alerts.

Provide a natural-language instruction describing what to investigate. Optionally set a title, share with teams via teamNames, or pick an agent profile via agentProfileId.

The investigation runs asynchronously and usually takes several minutes: this returns investigationId, chatId, and a url to open it in Grafana immediately, before the investigation finishes.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `instruction` (`string`, required): What to investigate, in natural language. Include the symptom, affected service/resource, and time range when known.
- `agentProfileId` (`string`, optional): Optional. Agent profile ID to run the investigation with. Uses the default profile when omitted.
- `teamNames` (`array`, optional): Optional. Grafana team names to share the investigation with. The caller must be a member of each team.
- `title` (`string`, optional): Optional. Short human-readable title for the investigation. Generated from the instruction when omitted.

Example input: `{"instruction":"<instruction>"}`

### `grafanacloudmcp_create_snapshot`

Create snapshot · Write

Create a Grafana snapshot from a full dashboard payload. Supports optional expiration and external snapshot fields.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `dashboard` (`object`, required): Complete dashboard model to snapshot (as returned by Grafana dashboard APIs)
- `deleteKey` (`string`, optional): Secret key for deleting external snapshots. Required when external is true
- `expires` (`integer`, optional): Snapshot expiration in seconds (e.g. 3600 for 1 hour)
- `external` (`boolean`, optional): Store snapshot on external server. Requires key and deleteKey when true
- `key` (`string`, optional): Custom snapshot key. Required when external is true
- `name` (`string`, optional): Optional snapshot name

Example input: `{"dashboard":{}}`

### `grafanacloudmcp_frontend_observability_handler`

Frontend Observability · Write

Manage Frontend Observability apps and inspect their browser telemetry on this Grafana stack.

Commands: list returns paginated app summaries and links; get returns one app by appId; web-vitals reports Core Web Vitals by page; errors ranks browser error groups with page and error links; create creates an app and returns Faro SDK installation snippets. App IDs are available from list. Create requires a grant with grafana:write. The other commands work with grafana:read.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `command` (`string`, required): The command to execute: list (paginated app summaries), get (specific app by ID), create (new app), web-vitals (retrieve Core Web Vitals for an app), or errors (rank the app's browser error groups). One of: `list`, `get`, `create`, `web-vitals`, `errors`.
- `appId` (`number`, optional): The ID of the Frontend Observability app (required for get, web-vitals, and errors commands)
- `corsOrigins` (`array`, optional): CORS origins allowed to send data to this app (optional for create command)
- `datasourceUid` (`string`, optional): UID of the Loki datasource holding this app's Faro telemetry. Only needed when web-vitals or errors reports that resolution was ambiguous — it names the candidates.
- `extraLogLabels` (`array`, optional): Additional log labels to attach to all telemetry data from this app (optional for create command)
- `limit` (`integer`, optional): Maximum results for list (default 50, integer) or errors (default 10), max 50
- `name` (`string`, optional): Name of the Frontend Observability app to create (required for create command)
- `nonSnippetAttributes` (`object`, optional): Optional attributes that affect snippet generation but are not part of the snippet (optional for create command)
- `offset` (`integer`, optional): Zero-based offset in the filtered app list for list (default 0).
- `pageId` (`string`, optional): Filter to a single page path, e.g. "/checkout" (optional for web-vitals and errors commands)
- `query` (`string`, optional): Case-insensitive app name substring for list.
- `rangeHours` (`number`, optional): Lookback window in hours for the web-vitals and errors commands (default 24)
- `userConfig` (`object`, optional): Optional user configuration for Faro SDK initialization (optional for create command)

Example input: `{"command":"list"}`

### `grafanacloudmcp_generate_deeplink`

Generate navigation deeplink · Write

Generate deeplink URLs for Grafana resources. Supports dashboards (requires dashboardUid or provisioningPreview), panels (requires dashboardUid or provisioningPreview, plus panelId), and Explore queries (requires datasourceUid and optionally queries). For dashboard and panel links, provisioningPreview points at a dashboard staged on a provisioning repository branch (e.g. a git-sync PR preview). For explore links, the time range and queries are embedded inside the Grafana explore state. Set shorten=true to return a /goto/<uid> short URL instead; if shortening fails, an error containing the full deeplink is returned.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `resourceType` (`string`, required): Type of resource: dashboard, panel, or explore
- `dashboardUid` (`string`, optional): Dashboard UID (for stored dashboards). Mutually exclusive with provisioningPreview for dashboard and panel types.
- `datasourceUid` (`string`, optional): Datasource UID (required for explore type)
- `panelId` (`integer`, optional): Panel ID (required for panel type)
- `provisioningPreview` (`object`, optional): Identifies a dashboard staged on a provisioning repository branch (e.g. a git-sync PR preview). Mutually exclusive with dashboardUid for dashboard and panel types.
- `queries` (`array`, optional): List of query objects for explore links (e.g. [{"refId":"A","expr":"up"}])
- `queryParams` (`object`, optional): Additional URL query parameters (for dashboard/panel types)
- `shorten` (`boolean`, optional): If true, try to shorten the generated URL to /goto/<uid>. If shortening fails, an error containing the full deeplink is returned.
- `timeRange` (`object`, optional): Time range for the link

Example input: `{"resourceType":"<resourceType>"}`

### `grafanacloudmcp_install_plugin`

Install plugin · Write

Install a Grafana plugin by its plugin ID. When version is omitted, the tool looks up the latest version and returns it without installing; supplying a version installs that version.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `pluginId` (`string`, required): The plugin ID to install (e.g. 'grafana-image-renderer', 'grafana-piechart-panel')
- `version` (`string`, optional): The exact version to install. When omitted, the tool returns the latest available version without installing.

Example input: `{"pluginId":"grafana-image-renderer"}`

### `grafanacloudmcp_agento11y_manage_eval_collections`

Manage Agent Observability saved conversations and collections · Destructive

Manage the curated conversations of Grafana Agent Observability (the grafana-agento11y-app plugin): bookmark conversations as saved conversations and group them into collections.

Two linked resources:
- A saved conversation (/eval/saved-conversations) is a bookmark on one conversation, keyed by a saved_id you choose. It gives that conversation a stable ID, a name, and tags a collection can reference. It does not preserve the conversation: retention deletes the bookmark and its collection memberships together with the conversation it points at.
- A collection (/eval/collections) is a named group of saved conversations, used as the source material for offline evaluation. Collections hold saved conversations, never raw conversation IDs, so a conversation must already be bookmarked before a collection accepts it.

Operations:
- 'list_saved_conversations': bookmarked conversations in this tenant, filterable by source ('telemetry' for bookmarked production traffic, 'manual' for hand-built ones). Also reports total_count for the whole filtered set, not just the page
- 'get_saved_conversation': one bookmark by ID
- 'list_collections_for_saved_conversation': the collections one bookmark belongs to (unpaginated)
- 'list_collections': collections in this tenant, each with its member_count
- 'get_collection': one collection by ID
- 'list_collection_members': the saved conversations in a collection
- 'save_conversation': bookmark a live conversation by conversation_id. saved_id is optional and defaults to 'saved-<conversation_id>'; a conversation can only be saved once, so a repeat returns 409 naming the existing saved_id
- 'delete_saved_conversation': delete a bookmark by saved_id. Idempotent, and it also removes the bookmark from every collection it belonged to, with no separate membership cleanup. On a source='manual' bookmark the backend goes further and deletes the underlying conversation and its generations, so the content itself is gone
- 'create_collection': create an empty collection from a name and optional description. The response carries the server-assigned collection_id needed by the membership operations
- 'update_collection': patch a collection's name or description. Omitted fields are left unchanged, and an explicitly empty description clears it
- 'delete_collection': delete a collection and its memberships in one transaction. Idempotent, and the saved conversations themselves are kept
- 'add_collection_members': add saved_ids to a collection. Every ID must already be a saved conversation (a missing one returns 400 naming it), and re-adding an existing member is a no-op
- 'remove_collection_member': drop one saved conversation from a collection. Idempotent, and the bookmark itself is kept

Identifiers: saved_id is caller-chosen and accepts letters, digits, '_', '.', ':', and '-' (looser than the evaluator and rule IDs, which reject hyphens). collection_id is a UUID assigned by the server when a collection is created; it cannot be chosen.

List rows are already enriched: every saved conversation in 'list_saved_conversations' and 'list_collection_members' embeds the collections it belongs to plus generation_count, total_tokens, agent_names, models, model_providers, and tags. Read those fields instead of calling 'list_collections_for_saved_conversation' per row, which is one request per result. An absent collections field means the row was not enriched; an empty array means the row genuinely belongs to no collection.

Pagination: when a response carries next_cursor, call the same operation again with cursor set to it. Echo the value back exactly; never construct or increment one. 'list_saved_conversations' returns an opaque numeric value while 'list_collections' and 'list_collection_members' return the last row ID, so a cursor from one operation passed to another fails or silently skips rows. Keep the same source filter across pages.

Permissions: reads need grafana-agento11y-app.data:read (Agento11y Editor or Admin). Every write needs grafana-agento11y-app.eval:write, granted only by the Agento11y Admin role; an Editor token gets 403.

When to use:
- Reading what is already curated: which collections exist, how large they are, and what is in them
- Turning a triaged failure into a regression collection: 'save_conversation', then 'create_collection' or 'add_collection_members'
- Bookmarking a live conversation so a collection can reference it by a stable ID
- Collection hygiene: renaming a collection, or removing a conversation that no longer belongs in it

When NOT to use:
- Searching or reading live conversations and generations
- Inspecting evaluators or the rules that schedule them

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `operation` (`string`, required): The operation to perform. Reads: 'list_saved_conversations', 'get_saved_conversation', 'list_collections_for_saved_conversation', 'list_collections', 'get_collection', 'list_collection_members'. Writes: 'save_conversation' (bookmark a conversation), 'delete_saved_conversation', 'create_collection', 'update_collection' (PATCH, partial), 'delete_collection', 'add_collection_members', 'remove_collection_member'. One of: `list_saved_conversations`, `get_saved_conversation`, `list_collections_for_saved_conversation`, `list_collections`, `get_collection`, `list_collection_members`, `save_conversation`, `delete_saved_conversation`, `create_collection`, `update_collection`, `delete_collection`, `add_collection_members`, `remove_collection_member`.
- `collection_id` (`string`, optional): Collection ID. Required for 'get_collection', 'list_collection_members', 'update_collection', 'delete_collection', 'add_collection_members', and 'remove_collection_member'. Rejected by 'create_collection' (the API assigns a UUID) and by 'save_conversation' (bookmarking cannot also add to a collection).
- `conversation_id` (`string`, optional): Conversation to bookmark (required for 'save_conversation').
- `cursor` (`string`, optional): Pagination cursor from a previous response's next_cursor, echoed back exactly and never constructed or incremented. A cursor belongs to the operation and filters that produced it: 'list_saved_conversations' returns an opaque numeric value while 'list_collections' and 'list_collection_members' return the last row ID, so they are not interchangeable.
- `description` (`string`, optional): Collection description (for 'create_collection' and 'update_collection'). On 'update_collection' an omitted description is left unchanged and an explicitly empty string clears it.
- `limit` (`integer`, optional): Maximum number of results per page (default 50, max 500) (for the paginated list operations)
- `name` (`string`, optional): Human-readable name. Required for 'save_conversation' and 'create_collection'; optional for 'update_collection', where an omitted name is left unchanged and a blank one is rejected.
- `saved_id` (`string`, optional): Saved conversation ID. Required for 'get_saved_conversation', 'list_collections_for_saved_conversation', 'delete_saved_conversation', and 'remove_collection_member'. Optional for 'save_conversation', which derives 'saved-<conversation_id>' when it is omitted. Only letters, digits, '_', '.', ':', and '-' are accepted.
- `saved_ids` (`array`, optional): Saved conversation IDs to add to a collection (required, non-empty, for 'add_collection_members'; rejected by 'create_collection', which always creates an empty collection). Every ID must already be a saved conversation; bookmark it with 'save_conversation' first. Re-adding a member is a no-op.
- `source` (`string`, optional): Saved conversation source filter: 'telemetry' for bookmarked production conversations, 'manual' for hand-built ones (for 'list_saved_conversations'). One of: `telemetry`, `manual`.
- `tags` (`object`, optional): Optional string tags to store on a bookmark (for 'save_conversation')

Example input: `{"operation":"list_saved_conversations"}`

### `grafanacloudmcp_agento11y_manage_eval_rules`

Manage Agent Observability eval rules and guards · Destructive

Manage the evaluation rules and guards of Grafana Agent Observability (the grafana-agento11y-app plugin): the configuration that decides when evaluators run.

Two different resources with different runtime behavior:
- Eval rules (/eval/rules) are asynchronous. A rule selects production traffic (selector, match filters, sample_rate) and schedules its evaluator_ids to score matching generations after the fact. Rules only observe; they never change a request.
- Guards (/eval/hook-rules; there is no /eval/guards path) run inline on the request path and can deny it, redact content, or block tool calls. A guard is inert until the agent application calls the hooks endpoint (POST /eval/hooks:evaluate) itself: a stored guard on its own changes nothing.

Operations:
- 'list_rules': asynchronous eval rules in this tenant (paginated)
- 'get_rule': one eval rule by ID
- 'list_guards': guards, read from /eval/hook-rules (paginated)
- 'get_guard': one guard by ID
- 'create_rule': create an asynchronous eval rule from an inline 'definition'
- 'update_rule': patch an existing rule; send only the fields to change (rule_id is taken from the 'rule_id' parameter and must not appear in the definition)
- 'delete_rule': delete a rule by ID
- 'preview_rule': dry-run a selector, match, and sample_rate against recent traffic and return how many generations would match and be sampled, plus example generations. Run this before creating a rule that spends judge tokens
- 'create_guard': create an inline guard (stored as a hook rule)
- 'update_guard': full replace of a guard (PUT, not PATCH) — omitted fields reset to server defaults, so send the complete definition, normally a 'get_guard' result with your edits applied
- 'delete_guard': delete a guard by ID

Identifiers (rule_id) accept only letters, digits, '_', and '.'; hyphens are rejected by the API. Rule selectors: user_visible_turn, all_assistant_generations, tool_call_steps, errored_generations, conversation (guards also accept 'all'). Match keys are arrays and include agent_name, agent_version, operation_name, model.provider, model.name, mode, error.type, error.category, and tags.<key>. Pagination: when a response carries next_cursor, call the same operation again with cursor set to it.

Permissions: reads need grafana-agento11y-app.data:read (Agento11y Editor or Admin). Every write, plus 'preview_rule' (which persists nothing), needs grafana-agento11y-app.eval:write, granted only by the Agento11y Admin role; an Editor token gets 403.

When to use:
- A score names an evaluator and you need to know which rule scheduled it and on what traffic
- Auditing which guards are live and whether they warn or deny
- Binding a new evaluator to production traffic with 'create_rule', after checking the blast radius with 'preview_rule'
- Adding a guard, or promoting one from warn to deny after watching its false-positive rate

When NOT to use:
- Inspecting what an evaluator checks, or the template it came from
- Listing conversations, generations, or scores

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `operation` (`string`, required): The operation to perform. Reads: 'list_rules', 'get_rule', 'list_guards', 'get_guard'. Writes: 'create_rule', 'update_rule' (PATCH, partial), 'delete_rule', 'preview_rule' (dry-run a selector and match against recent traffic, stores nothing), 'create_guard', 'update_guard' (PUT, full replace), 'delete_guard'. One of: `list_rules`, `get_rule`, `list_guards`, `get_guard`, `create_rule`, `update_rule`, `delete_rule`, `preview_rule`, `create_guard`, `update_guard`, `delete_guard`.
- `cursor` (`string`, optional): Pagination cursor from a previous response's next_cursor (for 'list_rules' and 'list_guards')
- `definition` (`object`, optional): Request body for the create/update/preview operations. Eval rules ('create_rule', 'update_rule'): rule_id (string, required on create, only letters/digits/underscore/dot), enabled (bool), selector (user_visible_turn|all_assistant_generations|tool_call_steps|errored_generations|conversation), match (object of string arrays, e.g. {"agent_name": ["my-agent"]}), sample_rate (0-1), evaluator_ids (array, the evaluators must already exist), alert_rule_uids (array), min_idle_seconds (int, required when selector is 'conversation': the idle period after which a conversation counts as finished; with that selector sample_rate applies per conversation, not per generation). 'update_rule' is a PATCH: send only the fields to change and do NOT include rule_id, which the API rejects as an unknown field - it is taken from the rule_id parameter. 'preview_rule': selector, match, sample_rate, and optionally rule_id. Guards ('create_guard', 'update_guard'): rule_id (required on create; on update it must match the rule_id parameter), enabled (bool), phase (preflight|postflight, default preflight), priority (int, lower runs first), selector (as above, plus 'all'), match (as above), action_on_fail (warn|deny - start with warn, which records the outcome without blocking the request, and promote to deny only after watching the false-positive rate), short_circuit (bool), and exactly ONE decision shape: evaluator_ids (an evaluator decides), redact ({patterns: [{id, regex}]} - each entry is exactly id and regex, a 'replacement' key returns 400, and the placeholder is derived from id) or tool_filter ({blocked_names: [glob]}). 'update_guard' is a PUT full replace: fields you omit reset to server defaults, so send a complete definition (normally a 'get_guard' result with your edits).
- `limit` (`integer`, optional): Maximum number of results per page (default 50, max 500) (for 'list_rules' and 'list_guards')
- `rule_id` (`string`, optional): Eval rule ID (for the '_rule' operations) or guard ID (for the '_guard' operations). Required for 'get_rule', 'update_rule', 'delete_rule', 'get_guard', 'update_guard', and 'delete_guard'; for 'create_rule', 'create_guard', and 'preview_rule' the ID comes from 'definition'.

Example input: `{"operation":"list_rules"}`

### `grafanacloudmcp_agento11y_manage_evaluators`

Manage Agent Observability evaluators · Destructive

Manage the evaluator catalog of Grafana Agent Observability (the grafana-agento11y-app plugin): read evaluators, evaluator templates, and the judge model catalog, and create, test, or delete evaluators.

An evaluator is a scoring function (kind: llm_judge, json_schema, regex, or heuristic) that scores generations. Generation scores name the evaluator that produced them. Templates are versioned starting points for evaluators. Judge providers and models are the LLM backends an llm_judge evaluator can use.

Operations:
- 'list_evaluators': evaluators in this tenant (paginated)
- 'get_evaluator': one evaluator by ID, with its kind, config, and output_keys
- 'list_templates': evaluator templates, filterable by scope ('global' for built-ins, 'tenant' for locally created ones)
- 'get_template': one template with its config, output_keys, and version list
- 'list_template_versions': version history of a template, each version with its config and output_keys
- 'list_judge_providers': judge providers configured on this stack
- 'list_judge_models': judge models, optionally filtered by provider
- 'upsert_evaluator': create or update an evaluator from an inline 'definition'. POST is create-or-update keyed on definition.evaluator_id; there is no separate update operation, and re-using an existing 'version' returns 409, so bump the version to change an evaluator
- 'delete_evaluator': soft-delete an evaluator by ID. Rules and guards that reference it keep the reference and silently stop producing scores
- 'fork_template': derive a new evaluator from a template in one call. Prefer this over copying 'get_template' output into 'upsert_evaluator', which the API rejects
- 'test_evaluator': run an inline evaluator definition against one generation and return its scores without persisting anything. Useful for tuning a judge config before 'upsert_evaluator'

Identifiers (evaluator_id, template_id) accept only letters, digits, '_', and '.'; hyphens are rejected by the API. Template operations need a stack with the evaluator template store configured and return 404 otherwise. Pagination: when a response carries next_cursor, call the same operation again with cursor set to it.

Permissions: reads need grafana-agento11y-app.data:read (Agento11y Editor or Admin). Every write, plus 'test_evaluator' (which persists nothing), needs grafana-agento11y-app.eval:write, granted only by the Agento11y Admin role; an Editor token gets 403.

When to use:
- A generation score names an evaluator and you need to see what it checks
- Inspecting a template before deriving an evaluator from it
- Tuning an llm_judge config against a real generation with 'test_evaluator' before storing it
- Creating an evaluator so a rule or guard can reference it

When NOT to use:
- Finding which rule scheduled an evaluator, or which guard enforces it
- Listing conversations, generations, or scores

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `operation` (`string`, required): The operation to perform. Reads: 'list_evaluators', 'get_evaluator', 'list_templates', 'get_template', 'list_template_versions', 'list_judge_providers', 'list_judge_models'. Writes: 'upsert_evaluator' (create or update from 'definition'), 'delete_evaluator', 'fork_template' (derive an evaluator from a template), 'test_evaluator' (score one generation with an inline definition without storing it). One of: `list_evaluators`, `get_evaluator`, `list_templates`, `get_template`, `list_template_versions`, `list_judge_providers`, `list_judge_models`, `upsert_evaluator`, `delete_evaluator`, `fork_template`, `test_evaluator`.
- `cursor` (`string`, optional): Pagination cursor from a previous response's next_cursor (for the paginated list operations)
- `definition` (`object`, optional): Request body for 'upsert_evaluator', 'fork_template', and 'test_evaluator'. For 'upsert_evaluator': evaluator_id (string, required, only letters/digits/underscore/dot - hyphens are rejected), version (string, required - re-using an existing version returns HTTP 409, so bump it to change an evaluator), kind (llm_judge|json_schema|regex|heuristic), description (string), config (object, shape depends on kind), output_keys (array of {key, type, description, unit, pass_threshold, enum, min, max, pass_match, pass_value}). The evaluator ID lives in this body, not in a URL or the evaluator_id parameter. For 'fork_template': evaluator_id (required) plus optional version (which template version to fork, defaults to the template's latest), config, and output_keys overrides. For 'test_evaluator': kind, config, and output_keys of the evaluator to try - the API rejects evaluator_id and version here, and nothing is persisted.
- `evaluator_id` (`string`, optional): Evaluator ID (required for 'get_evaluator' and 'delete_evaluator'). For 'upsert_evaluator' and 'fork_template' the evaluator ID belongs in 'definition' instead, because the API reads it from the request body.
- `generation_id` (`string`, optional): Generation to score (required for 'test_evaluator').
- `limit` (`integer`, optional): Maximum number of results per page (default 50, max 500) (for the paginated list operations)
- `provider` (`string`, optional): Judge provider ID to filter models by, e.g. 'openai' (for 'list_judge_models')
- `scope` (`string`, optional): Template scope filter: 'global' for built-in templates, 'tenant' for templates created in this tenant (for 'list_templates'). One of: `global`, `tenant`.
- `template_id` (`string`, optional): Template ID (required for 'get_template', 'list_template_versions', and 'fork_template')

Example input: `{"operation":"list_evaluators"}`

### `grafanacloudmcp_agento11y_manage_experiments`

Manage Agent Observability experiments · Destructive

Manage the offline experiments of Grafana Agent Observability (the grafana-agento11y-app plugin), their trials, and their scores.

An experiment is one offline run of an agent over a test suite. Each test case in the suite produces one or more trials, each trial is scored by the experiment's evaluators, and the experiment reports a pass rate. Experiments are created by SDK runners, not from here.

Operations:
- 'list': experiments in this tenant, filterable by suite_id, status, source, created_by, tag, and a created_at or completed_at window. Each row carries the same result summary as 'get', so finding the experiment that regressed needs no second call
- 'get': one experiment with its result summary: pass rate, average final score, total cost and tokens
- 'get_report': the per-test-case breakdown, trimmed by row_limit. The test case input and expected values, the score records, and the artifact records are dropped because those fields have no size bound; each trial keeps its error message, a score_count, an artifact_count, and the IDs the drill-downs take
- 'list_trials': one experiment's trials, paginated. Prefer this over 'get_report' on a large suite. It reports no cost or token counts: only the report path fills those in
- 'list_scores': every score in one experiment, paginated
- 'get_trial': one trial in full, including the test case snapshot with its input and expected values
- 'list_trial_scores': one trial's scores, with the explanation each judge wrote
- 'list_trial_artifacts': one trial's artifact metadata, with a content_ref rather than the bytes
- 'list_facets': the distinct suites, owners, and tags across every experiment in the tenant, for building a 'list' filter. Only source, from, and to narrow it; it rejects a filter it would otherwise have to ignore
- 'update': patch an experiment's name, description, tags, or metadata. Only the experiment's created_by may patch it, so patching an experiment someone else started answers 401
- 'cancel': stop a running experiment. It checks no owner, so any caller with the write permission can stop any experiment. An experiment that already finished is left alone: the call answers 200 and returns it unchanged instead of failing, so read the status on the result rather than assume a run was stopped

Size: 'get_report' is fetched whole before it is trimmed, and a response above 10 MiB fails the call rather than arriving truncated.

Pagination: when a response carries next_cursor, call the same operation again with cursor set to it, repeating the first page's filters with absolute RFC3339 times. A relative bound such as now-7d re-resolves between calls and moves the window the cursor was issued against, so it is rejected alongside a cursor.

Permissions: reads need grafana-agento11y-app.data:read (Agento11y Editor or Admin). Both writes need grafana-agento11y-app.eval:write, granted only by the Agento11y Admin role; an Editor token gets 403.

When to use:
- Finding the last experiment for a suite after a suspected regression: 'list' by suite_id, then read the pass rate off the row
- Finding which test cases an experiment failed on, then reading one failing trial in full
- Labelling an experiment after triage, so 'list' by tag finds it later
- Stopping an experiment that is burning judge tokens on a broken candidate

When NOT to use:
- Reading scores on live production traffic
- Inspecting the test cases a suite defines, or editing them
- Inspecting what an evaluator checks

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `operation` (`string`, required): The operation to perform. Reads: 'list', 'get', 'get_report', 'list_trials', 'list_scores', 'get_trial', 'list_trial_scores', 'list_trial_artifacts', 'list_facets'. Writes: 'update' (PATCH the name, description, tags, or metadata of an experiment), 'cancel' (stop a running experiment). One of: `list`, `get`, `get_report`, `list_trials`, `list_scores`, `get_trial`, `list_trial_scores`, `list_trial_artifacts`, `list_facets`, `update`, `cancel`.
- `completed_from` (`string`, optional): Start of the completed_at window in RFC3339 or relative format (for 'list'). 'from' and 'to' filter created_at; this pair filters completed_at instead, so it drops runs that have not finished.
- `completed_to` (`string`, optional): End of the completed_at window in RFC3339 or relative format (for 'list')
- `created_by` (`string`, optional): Owner filter, matched against the values 'list_facets' reports under owners (for 'list')
- `cursor` (`string`, optional): Pagination cursor from a previous response's next_cursor, echoed back exactly and never constructed or incremented. Repeat the same filters as the first call, using absolute RFC3339 times.
- `description` (`string`, optional): New experiment description (for 'update'). An omitted field is left unchanged and an explicitly empty string clears it.
- `experiment_id` (`string`, optional): Experiment ID from 'list'. Required for 'get', 'get_report', 'list_trials', 'list_scores', 'update', and 'cancel'.
- `from` (`string`, optional): Start of the created_at window in RFC3339 or relative format (e.g. now-7d), for 'list' and 'list_facets'
- `limit` (`integer`, optional): Maximum number of results per page (default 50, max 500) (for the paginated list operations)
- `metadata` (`object`, optional): Replacement metadata object (for 'update'). A finished experiment rejects it with 409.
- `name` (`string`, optional): New experiment name (for 'update'). An omitted field is left unchanged, and a blank name is rejected. A finished experiment accepts only description and tags, so renaming one returns 409.
- `order` (`string`, optional): Sort order for 'list', newest first either way. Defaults to 'created_at_desc'. 'completed_at_desc' returns a single page and cannot be combined with a cursor. One of: `created_at_desc`, `completed_at_desc`.
- `row_limit` (`integer`, optional): Maximum number of test case rows 'get_report' returns (default 50, max 500). The report route is not paginated, so this trims the returned rows and sets rows_truncated; it does not reduce what the plugin sends.
- `source` (`string`, optional): Experiment origin filter: 'collection' for runs built from a saved collection, 'external' for runs reported by an SDK runner (for 'list' and 'list_facets'). One of: `collection`, `external`.
- `status` (`string`, optional): Experiment status filter (for 'list'). A finished run is 'completed'; there is no 'succeeded' status. One of: `running`, `completed`, `failed`, `canceled`.
- `suite_id` (`string`, optional): Test suite ID filter (for 'list')
- `tag` (`array`, optional): Experiment tag filter (for 'list'). Several tags match an experiment carrying any of them, not all of them.
- `tags` (`array`, optional): Replacement tag list for 'update'. It overwrites the whole list rather than adding to it, so run 'get' first and send the existing tags plus the new ones; an explicitly empty array clears them. The tag filter for 'list' is the separate 'tag' parameter.
- `to` (`string`, optional): End of the created_at window in RFC3339 or relative format (e.g. now), for 'list' and 'list_facets'
- `trial_id` (`string`, optional): Trial ID from 'list_trials' or 'get_report' (required for 'get_trial', 'list_trial_scores', and 'list_trial_artifacts')

Example input: `{"operation":"list"}`

### `grafanacloudmcp_agento11y_manage_test_suites`

Manage Agent Observability test suites · Destructive

Manage the test suites of Grafana Agent Observability (the grafana-agento11y-app plugin), their versions, and their test cases.

A test suite is the input side of an offline experiment: a named set of test cases that an SDK runner replays against an agent. Suites are versioned, and a test case belongs to one version rather than to the suite, so every test case operation takes both suite_id and version.

A version is either a draft or published. A draft accepts test case edits; publishing freezes it and makes it the suite's latest_version, which is the version a runner picks up. A suite has at most one draft at a time.

Operations:
- 'list_suites': the test suites in this tenant, newest first. The rows carry no version history
- 'get_suite': one suite with its full version history under versions
- 'list_test_cases': the test cases of one suite version, oldest first, paginated
- 'get_test_case': one test case in full, with its free-form input and expected values
- 'create_suite': a new empty suite. It has no version yet, so follow it with 'create_draft_version'
- 'update_suite': patch a suite's name, description, or tags
- 'create_draft_version': open a new editable version. A suite that already has a draft answers 409
- 'publish_version': freeze a draft. There is no unpublish; a published version answers 409 to a second publish and to every test case edit, so changing a published suite means a new draft
- 'upsert_test_case': write a whole test case into a draft version. It replaces the stored case rather than merging into it, so a field left out is cleared; read the case with 'get_test_case' first and send it back complete
- 'delete_test_case': remove one test case from a draft version. Deleting a test case that is already gone answers 404

Pagination: when a response carries next_cursor, call the same operation again with cursor set to it.

Permissions: reads need grafana-agento11y-app.data:read (Agento11y Editor or Admin). Every write needs grafana-agento11y-app.eval:write, granted only by the Agento11y Admin role; an Editor token gets 403.

When to use:
- Reading the test cases at the version an experiment used, after it reported a failing case
- Adding a regression case to a suite, then publishing the draft so the next experiment picks it up
- Correcting a test case whose expected value was wrong

When NOT to use:
- Reading how a suite scored, or the trials, scores, and artifacts behind it
- Changing what an evaluator checks

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `operation` (`string`, required): The operation to perform. Reads: 'list_suites', 'get_suite', 'list_test_cases', 'get_test_case'. Writes: 'create_suite', 'update_suite' (PATCH the name, description, or tags), 'create_draft_version' (open an editable version), 'publish_version' (freeze it), 'upsert_test_case' (write a whole case into a draft), 'delete_test_case'. One of: `list_suites`, `get_suite`, `list_test_cases`, `get_test_case`, `create_suite`, `update_suite`, `create_draft_version`, `publish_version`, `upsert_test_case`, `delete_test_case`.
- `artifact_refs` (`array`, optional): Artifacts the case refers to, each an artifact_id with its name and kind (for 'upsert_test_case')
- `category` (`string`, optional): Test case category (for 'upsert_test_case')
- `changelog` (`string`, optional): Note describing what the new version changes (for 'create_draft_version')
- `cursor` (`string`, optional): Pagination cursor from a previous response's next_cursor, echoed back exactly and never constructed or incremented
- `description` (`string`, optional): Suite or test case description. An omitted field is left unchanged by 'update_suite' and an explicitly empty string clears it.
- `empty_draft` (`boolean`, optional): Start the new version with no test cases (for 'create_draft_version'). The default copies every case of the latest published version, which is what an edit to an existing suite wants.
- `expected` (`object`, optional): What the case expects back (for 'upsert_test_case'). Free-form, and read by the evaluators rather than compared by the API.
- `input` (`object`, optional): What the case feeds the agent (required and non-empty for 'upsert_test_case'). The shape is free-form and decided by the runner, so copy an existing case of the suite before inventing one.
- `limit` (`integer`, optional): Maximum number of results per page (default 50, max 500) (for the list operations)
- `metadata` (`object`, optional): Free-form metadata object (for 'upsert_test_case')
- `name` (`string`, optional): Suite name. Required and non-blank for 'create_suite'. For 'update_suite' an omitted name is left unchanged and a blank one is rejected. For 'upsert_test_case' it names the case.
- `suite_id` (`string`, optional): Test suite ID from 'list_suites'. Required for every operation except 'list_suites', which takes none, and 'create_suite', where it is an optional caller-chosen ID that must not already exist.
- `tags` (`array`, optional): Replacement tag list for 'update_suite' and 'upsert_test_case'. It overwrites the whole list rather than adding to it, so read the current tags first; an explicitly empty array clears them.
- `test_case_id` (`string`, optional): Test case ID. Required for 'get_test_case' and 'delete_test_case'. For 'upsert_test_case' it selects an existing case to replace; omit it to have one created.
- `version` (`string`, optional): Suite version such as 'v3', taken from the versions list of 'get_suite'. Required for 'publish_version', 'list_test_cases', 'get_test_case', 'upsert_test_case', and 'delete_test_case'. 'create_draft_version' assigns the next version itself, so do not send one.

Example input: `{"operation":"list_suites"}`

### `grafanacloudmcp_alerting_rules_write`

Write alert rules · Destructive

Create, update, and delete Grafana alert rules.

When to use:
- Creating, updating, or deleting alert rules

Operation 'update' replaces the whole rule: it takes all required fields, not only the changed ones.

Creation defaults to Grafana-managed, even when queries use an external datasource.
Use managed_by='datasource' when requested or when established conversation or environment context clearly identifies a datasource-managed workflow. An external query datasource or an empty Grafana rule list alone is insufficient. Ask if context conflicts.
Datasource-managed creation uses a Mimir/Cortex or Loki ruler with namespace, rule_group, title and expression. datasource_uid is optional if exactly one compatible datasource exists. Ambiguity returns candidates for selection. Never falls back to Grafana-managed creation.

Does not list or inspect rules, and does not manage notification routing.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `operation` (`string`, required): The operation to perform: 'list', 'get', 'versions', 'create', 'update', or 'delete'. To create a rule, use operation 'create' and provide all required fields in a single call. To update a rule, first use 'get' to retrieve its full configuration, then 'update' with all required fields plus your changes. One of: `list`, `get`, `versions`, `create`, `update`, `delete`.
- `annotations` (`object`, optional): Optional annotations for the alert rule
- `condition` (`string`, optional): Grafana-managed only. The query condition identifier, e.g. 'A', 'B' (required for 'create', 'update')
- `data` (`array`, optional): Grafana-managed only. Array of alert query objects (required for 'create'/'update'). Each object has: datasourceUid (string, required), model (object with expr for data queries or type/expression/conditions for expressions), refId (string, auto-assigned if omitted), relativeTimeRange ({from, to} in seconds, defaults to {from:600,to:0}). For server-side expressions use datasourceUid '__expr__'. Example: [{datasourceUid: 'prometheus', model: {expr: 'up == 0'}}, {datasourceUid: '__expr__', model: {type: 'threshold', expression: 'A', conditions: [{evaluator: {type: 'gt', params: [0]}}]}}]
- `datasource_uid` (`string`, optional): Datasource UID for list or explicit managed_by=datasource creation. For creation omit to select the sole compatible datasource. Ambiguity returns candidates for selection.
- `disable_provenance` (`boolean`, optional): If true, the alert remains editable in the Grafana UI (sets X-Disable-Provenance header). Defaults to true.
- `evaluation_interval` (`string`, optional): Interval for a new datasource rule group (default 1m). Must match an existing group's interval if supplied.
- `exec_err_state` (`string`, optional): Grafana-managed only. State on execution error: NoData, Alerting, OK (required for 'create', 'update')
- `expression` (`string`, optional): PromQL or LogQL expression for datasource-managed creation.
- `folder_uid` (`string`, optional): The folder UID. For 'list': filter by exact folder UID (mutually exclusive with search_folder). For Grafana-managed 'create'/'update': required destination folder.
- `for` (`string`, optional): Duration before alert fires, e.g. '5m'. Required for Grafana-managed create/update. Optional for datasource-managed rules (default 0s).
- `is_paused` (`boolean`, optional): If true, the alert rule remains inactive, Default is false
- `keep_firing_for` (`string`, optional): Enables continous firing of alert for specified time even when condition is no longer met. Default is 0 (resolves immediately)
- `label_selectors` (`array`, optional): Prometheus-style selectors to filter alert rules by labels. Each string is a selector e.g. '{severity="critical", team=~"backend.*"}'. All selectors must match (AND).
- `labels` (`object`, optional): Optional labels for the alert rule
- `limit_alerts` (`integer`, optional): Limit alert instances per rule. For list: 0 omits alerts. For get: <=0 defaults to 200. Max 200.
- `managed_by` (`string`, optional): Creation target. Omission defaults to Grafana-managed. Select datasource when requested or clearly established by conversation or environment context. Other mutations remain Grafana-only. One of: `grafana`, `datasource`. Default: `grafana`.
- `matchers` (`array`, optional): Label matchers to filter alert instances. Each string is a Prometheus-style matcher e.g. 'severity="critical"', 'env!="dev"', 'team=~"backend.*"'. Requires Grafana 12.4+.
- `missing_series_evals_to_resolve` (`integer`, optional): Consecutive evaluation intervals with no data required to mark the alert as resolved. Default is 2.
- `namespace` (`string`, optional): Namespace for datasource-managed creation. Required with managed_by=datasource.
- `no_data_state` (`string`, optional): Grafana-managed only. State when no data: NoData, Alerting, OK (required for 'create', 'update')
- `notification_settings` (`object`, optional): Notification settings object. Fields: receiver (string, required), groupBy ([]string), groupWait/groupInterval/repeatInterval (duration strings), muteTimeIntervals/activeTimeIntervals ([]string).
- `org_id` (`integer`, optional): Grafana-managed organization ID (required for 'create', 'update')
- `record` (`object`, optional): Recording rule config. Fields: from (string, required - ref ID e.g. 'A'), metric (string, required - metric name), targetDatasourceUid (string, optional).
- `rule_group` (`string`, optional): The rule group name (required for 'create', 'update')
- `rule_limit` (`integer`, optional): Maximum number of rules to return (default 200, max 200). Requires Grafana 12.4+ (for 'list' operation). Default: `200`.
- `rule_type` (`string`, optional): Filter by rule type (for 'list' operation). One of: `alerting`, `recording`.
- `rule_uid` (`string`, optional): The UID of the alert rule (required for 'get', 'versions', 'update', 'delete'; optional for 'create')
- `search_folder` (`string`, optional): Search folders by path using partial matching (for 'list' operation). Requires Grafana 12.4+. Mutually exclusive with folder_uid.
- `search_rule_name` (`string`, optional): Search alert rule names/titles using partial matching. Requires Grafana 12.4+ (for 'list' operation)
- `states` (`array`, optional): Filter by alert state: firing, pending, normal, recovering, nodata, error (for 'list' operation)
- `title` (`string`, optional): The title of the alert rule (required for 'create', 'update')

Example input: `{"operation":"list"}`

### `grafanacloudmcp_alerting_silences_write`

Write alerting silences · Destructive

Create, update, and delete Grafana alerting silences. A silence temporarily suppresses notifications for alerts whose labels match a set of matchers, without changing the alert rules themselves.

Operations:
- 'create': create a new silence. Requires matchers, starts_at, ends_at (RFC3339) and comment.
- 'update': modify an existing silence by silence_id. Requires matchers, starts_at, ends_at and comment. The id is only kept when the posted matchers and starts_at match the stored ones, so pass back the stored starts_at of the silence; otherwise Alertmanager expires the old silence and returns a new id.
- 'delete': expire/remove a silence by silence_id.

When to use:
- Muting noisy or expected alerts during maintenance windows

Does not list or inspect silences, change alert rules, or manage notification routing.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `operation` (`string`, required): The operation to perform: 'list' to list silences, 'get' to retrieve a silence by id, 'create' to create a new silence, 'update' to modify an existing silence by id, 'delete' to expire a silence by id. One of: `list`, `get`, `create`, `update`, `delete`.
- `comment` (`string`, optional): A human-readable comment explaining the silence (required for 'create' and 'update')
- `created_by` (`string`, optional): Author of the silence. Defaults to 'grafana-assistant'.
- `ends_at` (`string`, optional): Silence end time in RFC3339 format, e.g. '2026-07-11T12:00:00Z' (required for 'create' and 'update')
- `matchers` (`array`, optional): Label matchers. Required (at least one) for 'create' and 'update'. For 'list', used as an optional filter.
- `rule_uid` (`string`, optional): Optional: filter listed silences to those scoped to this alert rule UID (matches the __alert_rule_uid__ label). Only used with 'list'.
- `silence_id` (`string`, optional): The silence id (required for 'get', 'update' and 'delete')
- `starts_at` (`string`, optional): Silence start time in RFC3339 format, e.g. '2026-07-11T10:00:00Z' (required for 'create' and 'update'). Grafana clamps a start time in the past to the moment of creation, so for 'update' pass back the starts_at returned by 'get' to keep the silence id stable.

Example input: `{"operation":"list"}`

### `grafanacloudmcp_ask_assistant`

Ask Grafana Assistant · Destructive

Send a message to Grafana Assistant and wait for the full text reply. The assistant may use tools, metrics, logs, and other stack context—broader than firing one isolated data-source query.

Suited to open-ended questions and triage that need assistant reasoning and tool use.

**Multi-turn:** each result includes a contextId; passing it back continues the same conversation.

**Time:** complex tasks can take several minutes; the call blocks until the reply is done or the request times out.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `prompt` (`string`, required): The question or instruction to send to Grafana Assistant (natural language).
- `contextId` (`string`, optional): Optional. Context ID from a previous response, to continue the same conversation.

Example input: `{"prompt":"<prompt>"}`

### `grafanacloudmcp_create_alert_creation`

Create alert rule · Destructive

Save the exact draft after the user's Create alert rule action. Retain ruleUid for status checks. Never automatically retry an uncertain write. Does not confirm evaluation or notification delivery.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `draft` (`object`, required): Draft

Example input: `{"draft":{}}`

### `grafanacloudmcp_delete_annotation`

Delete Annotation · Destructive

Permanently delete an annotation by ID. The annotation cannot be recovered afterwards.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `id` (`integer`, required): Annotation ID to delete

Example input: `{"id":1}`

### `grafanacloudmcp_delete_snapshot`

Delete snapshot · Destructive

Delete a Grafana snapshot by snapshot key.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `key` (`string`, required): Snapshot key to delete

Example input: `{"key":"<key>"}`

### `grafanacloudmcp_exec_gcx`

Run gcx command · Destructive

Run a gcx (Grafana Cloud CLI) command against the user's Grafana stack and return its output.

Use this as the fallback when no dedicated tool covers what you need, particularly for Grafana Cloud products without tools of their own here: SLO, IRM (OnCall and Incident), Fleet Management, Frontend Observability, Knowledge Graph, Database Observability, and more. Prefer a dedicated tool when one exists.

Use it like a CLI: pass gcx's arguments without the leading "gcx", one per array element, e.g. ["slo", "definitions", "list"]. gcx documents itself, so look up a command before guessing it:
1. ["help-tree", "--depth", "1", "-o", "text"] lists the top-level commands and the skills that cover them.
2. ["help-tree", "<command>", "-o", "text"] shows one area's subcommands, flags and usage hints; ["<command>", "<subcommand>", "--help"] shows full usage.
3. ["agent", "skills", "get", "<skill>"] prints step-by-step guidance for a task.
Don't run ["help-tree"] without a command, or ["commands"]: they print the whole CLI, 100 KB and more.

Output is JSON; narrow it with --json field1,field2, --jq '<expr>' or --limit.

The command runs in a sandbox, with the user's permissions, that can reach only this stack's Grafana and the grafana.com docs (gcx docs). Commands that need Grafana Cloud credentials (gcx cloud, k6, synthetic monitoring, adaptive metrics, logs and traces) or local setup (login, config, setup) fail, and the sandbox has no local files to read. Datasource queries need the grafana:query scope, commands that create, update or delete need grafana:write, and destructive ones need --force, since nothing can prompt for confirmation.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `args` (`string`, required): gcx arguments, without the program name

Example input: `{"args":"<args>"}`

### `grafanacloudmcp_grafana_api_request`

Grafana API request · Destructive

Make an authenticated HTTP request to the Grafana API. Similar to 'gh api' for GitHub. Supports any Grafana API endpoint with optional jq-style response filtering. Use this for API endpoints that don't have a dedicated tool.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `endpoint` (`string`, required): The API path relative to the Grafana base URL (e.g. '/api/org', '/api/dashboards/uid/abc123'). Must start with '/'.
- `body` (`string`, optional): Request body (JSON string). Used with POST, PUT, and PATCH requests.
- `headers` (`object`, optional): Additional HTTP headers to include in the request.
- `jq` (`string`, optional): A jq expression to filter or transform the JSON response (e.g. '.dashboards[] | .title').
- `method` (`string`, optional): HTTP method. Defaults to GET. One of: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`.

Example input: `{"endpoint":"/api/org"}`

### `grafanacloudmcp_query_influxdb`

Query InfluxDB · Destructive

Query an InfluxDB datasource via Grafana. Supports both InfluxQL (v1.x) and Flux (v2.x). The 'dialect' parameter selects the query language; if omitted it's inferred from the datasource configuration.

Time formats: 'now-1h', '2026-02-02T19:00:00Z', '1738519200000' (Unix ms)

InfluxQL example: SELECT mean("value") FROM "cpu" WHERE time > now() - 1h GROUP BY time(1m)
Flux example:    from(bucket: "metrics") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "cpu")

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `datasourceUid` (`string`, required): The UID of the InfluxDB datasource to query.
- `query` (`string`, required): Raw query string. InfluxQL for v1.x datasources (e.g. SELECT * FROM cpu WHERE time > now() - 1h), or Flux for v2.x datasources (e.g. from(bucket: "mybucket") |> range(start: -1h)).
- `dialect` (`string`, optional): Query dialect: 'influxql' or 'flux'. If omitted, inferred from the datasource's configured query language (v1 -> influxql, v2 -> flux).
- `end` (`string`, optional): End time for the query. Time formats: 'now', '2026-02-02T19:00:00Z', '1738519200000' (Unix ms). Defaults to now.
- `maxDataPoints` (`integer`, optional): Maximum number of data points to return. Default: 1000.
- `start` (`string`, optional): Start time for the query. Time formats: 'now-1h', '2026-02-02T19:00:00Z', '1738519200000' (Unix ms). Defaults to 1 hour ago.

Example input: `{"datasourceUid":"<datasourceUid>","query":"*"}`

### `grafanacloudmcp_query_sql`

Query SQL · Destructive

Query ClickHouse, Snowflake, Athena, MySQL, PostgreSQL, MSSQL, or BigQuery via Grafana. Supports datasource-specific time macros and template variables. BigQuery requires qualified project.dataset.table references; billing uses the datasource project.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `datasourceUid` (`string`, required): The UID of the SQL datasource.
- `query` (`string`, required): Raw SQL query. Supports datasource-specific macros such as $__timeFilter(column), $__from/$__to, $__interval, and ${varname} for variable substitution.
- `catalog` (`string`, optional): Data catalog override (Athena only). Defaults to datasource config.
- `database` (`string`, optional): Database override (Athena, Snowflake, ClickHouse). Defaults to datasource config.
- `end` (`string`, optional): End time. Formats: 'now', '2026-02-02T19:00:00Z', '1738519200000' (Unix ms). Default: now.
- `limit` (`integer`, optional): Maximum number of rows. Default: 100, Max: 1000. Appended as LIMIT when query has none; existing LIMIT clauses are capped at 1000.
- `location` (`string`, optional): BigQuery processing location (e.g. US or europe-west1). Defaults to datasource config.
- `region` (`string`, optional): AWS region override (Athena only). Defaults to datasource config.
- `resultReuseEnabled` (`boolean`, optional): Enable Athena query result reuse. Requires Athena engine version 3.
- `resultReuseMaxAgeInMinutes` (`integer`, optional): Max age in minutes for reused Athena results. Only applies when resultReuseEnabled is true.
- `schema` (`string`, optional): Schema override (Snowflake, PostgreSQL, MSSQL). Defaults to datasource config.
- `start` (`string`, optional): Start time. Formats: 'now-1h', '2026-02-02T19:00:00Z', '1738519200000' (Unix ms). Default: 1 hour ago.
- `variables` (`object`, optional): Template variable substitutions as key-value pairs. Referenced as ${varname} or $varname in the query.

Example input: `{"datasourceUid":"<datasourceUid>","query":"*"}`

### `grafanacloudmcp_update_alert_group`

Update IRM alert group · Destructive

Update the state of a Grafana OnCall alert group: acknowledge, unacknowledge, resolve, or unresolve it by ID. Returns the alert group's resulting OnCall state (one of new, acknowledged, resolved, silenced), or a stateWarning explaining why that state could not be read back after a successful update.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `alertGroupId` (`string`, required): The ID of the alert group to update
- `state` (`string`, required): New state for the alert group. One of: acknowledged, unacknowledged, resolved, unresolved

Example input: `{"alertGroupId":"<alertGroupId>","state":"<state>"}`

### `grafanacloudmcp_update_alert_status`

Update alert rule · Destructive

Silence one Grafana-managed alert rule for 2, 6 or 12 hours, or expire the displayed silences scoped only to it. Intended to be invoked by the rendered app after a user action. Requires the grafana:write scope and the caller's own Grafana permissions. Returns a receipt; the app refreshes status separately.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `operation` (`string`, required): No description. One of: `silence`, `unsilence`.
- `rule_uid` (`string`, required): Exact UID of the displayed Grafana-managed alert rule.
- `duration_hours` (`integer`, optional): Silence length in hours. Only for operation=silence. One of: `2`, `6`, `12`.
- `silence_ids` (`array`, optional): IDs of the displayed rule silences to expire. Required for, and only valid with, operation=unsilence. Each is re-checked to still be active and scoped only to the rule; others are left alone.

Example input: `{"operation":"silence","rule_uid":"<rule_uid>"}`

### `grafanacloudmcp_update_annotation`

Update Annotation · Destructive

Updates the provided properties of an annotation by ID. Only fields included in the request are modified; omitted fields are left unchanged.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `data` (`object`, optional): Optional JSON payload
- `id` (`integer`, optional): Annotation ID to update
- `tags` (`array`, optional): Tags to replace existing tags
- `text` (`string`, optional): New annotation text
- `time` (`integer`, optional): New start time epoch ms
- `timeEnd` (`integer`, optional): New end time epoch ms

Example input: `{}`

### `grafanacloudmcp_update_dashboard`

Create or update dashboard · Destructive

Create or update a dashboard. Returns the saved dashboard UID and dashboard link in the 'url' field, using the instance public URL when available. Two modes: (1) Full JSON — provide 'dashboard' for new dashboards or complete replacements. (2) Patch — provide 'uid' + 'operations' to make targeted changes to an existing dashboard. One of these two modes is required; 'folderUid', 'message', and 'overwrite' are supplementary and do nothing on their own. Dashboard authoring guidance: if a saved query must support one, many, or All values from a multi-select variable inside a regex expression or matcher, save '${var:regex}' rather than plain '$var'. Saved dashboard annotation queries/definitions live in dashboard JSON under 'annotations.list'; annotation events are stored separately and are not part of the dashboard JSON. For stat panels over the current dashboard range, make the query return the range-level result the stat should display; panel-side reduction only reduces returned series and does not compute peak-over-range or ratio-of-peaks semantics for you. Patch operations support JSONPaths like '$.panels[0].targets[0].expr', '$.panels[1].title', '$.panels[2].targets[0].datasource', '$.templating.list/-', and '$.annotations.list/-'. Append to arrays with '/- ' syntax: '$.panels/- '. Remove by index: {"op": "remove", "path": "$.panels[2]"}. Multiple removes on the same array are automatically reordered to avoid index-shifting issues. Note: only numeric array indices are supported in patch paths; filter expressions like [?(@.id==2)] and wildcards like [*] are not supported. Schema: prefer v2 for new dashboards; if this Grafana lacks v2 the save fails saying so, then send v1. Keep an existing dashboard in its stored schema (indicated by 'isV2'/'apiVersion' on the fetched dashboard). A body with top-level 'elements'/'layout' is saved as v2. Minimal v2 body: {"title":"T","timeSettings":{"from":"now-6h","to":"now"},"variables":[],"elements":{"p1":{"kind":"Panel","spec":{"id":1,"title":"Up","vizConfig":{"kind":"VizConfig","group":"timeseries","spec":{}},"data":{"kind":"QueryGroup","spec":{"queries":[{"kind":"PanelQuery","spec":{"refId":"A","query":{"kind":"DataQuery","group":"prometheus","datasource":{"name":"<ds uid>"},"spec":{"expr":"up"}}}}]}}}}},"layout":{"kind":"GridLayout","spec":{"items":[{"kind":"GridLayoutItem","spec":{"x":0,"y":0,"width":24,"height":8,"element":{"kind":"ElementReference","name":"p1"}}}]}}}. For tabs, layout is {"kind":"TabsLayout","spec":{"tabs":[{"kind":"TabsLayoutTab","spec":{"title":"A","layout":}}]}}.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `dashboard` (`object`, optional): The full dashboard JSON: classic v1 (panels[]) or v2 (elements/layout; skeleton in the tool description). Use for creating new dashboards or complete updates. Saved dashboard annotation queries/definitions live in 'annotations.list' inside this JSON; they are different from annotation events, which are stored separately. Large dashboards consume significant context - consider using patches for small changes.
- `folderUid` (`string`, optional): The UID of the dashboard's folder
- `message` (`string`, optional): Set a commit message for the version history
- `operations` (`array`, optional): Array of patch operations for targeted updates. More efficient than full dashboard JSON for small changes. Common paths: '$.templating.list/-' to add a variable, '$.annotations.list/-' to add a saved dashboard annotation query/definition, '$.panels[0].targets[0].expr' to replace a panel query. v2 paths: '$.elements.<name>.spec.title', '$.variables/-', '$.layout.spec.items/-'.
- `overwrite` (`boolean`, optional): Overwrite the dashboard if it exists. Otherwise create one
- `uid` (`string`, optional): UID of existing dashboard to update. Must be used together with 'operations'. Providing 'uid' without 'operations' will fail.
- `userId` (`integer`, optional): ID of the user making the change

Example input: `{}`

### `grafanacloudmcp_update_datasource`

Update datasource · Destructive

Update non-secret datasource fields by UID in two steps. Called with only the uid, it returns the datasource's field schema and changes nothing. Called with the uid, schemaReviewed=true, and the changed values in the fields map, it applies the update. Omitted fields are preserved. Secrets (passwords, tokens) cannot be changed. Returns an update message and a health check.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `uid` (`string`, required): UID of the datasource to update
- `access` (`string`, optional): proxy or direct
- `basicAuth` (`boolean`, optional): Enable basic auth
- `database` (`string`, optional): Database name
- `fields` (`object`, optional): Datasource field values to change, keyed by field key from the schema returned on the first call. The server uses each field's target (root or jsonData) to place values correctly, merging jsonData changes into the existing settings. Only include the fields you want to change. Example: {"httpMethod": "POST"}.
- `isDefault` (`boolean`, optional): Make this the default datasource
- `jsonData` (`object`, optional): Non-secret plugin settings; replaces existing jsonData when set
- `name` (`string`, optional): Display name
- `schemaReviewed` (`boolean`, optional): True once the field schema has been retrieved; required to apply the update.
- `url` (`string`, optional): Base URL

Example input: `{"uid":"<uid>"}`

### `grafanacloudmcp_update_incident`

Update incident · Destructive

Update an existing Grafana incident by ID. Allows changing the status ('active' or 'resolved'), the severity, the title, and custom field values. Only the provided fields are changed. Use this to resolve an incident, to correct its severity or title, or to fill in custom fields as part of an on-call workflow.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `incidentId` (`string`, required): The ID of the incident to update
- `customFields` (`array`, optional): Custom field values to set. Only the listed fields are changed
- `severity` (`string`, optional): The new severity of the incident, e.g. 'minor', 'major', 'critical'
- `status` (`string`, optional): The new status of the incident. Valid values: 'active', 'resolved'
- `title` (`string`, optional): The new title of the incident

Example input: `{"incidentId":"<incidentId>"}`

## Related

Other Monitoring connectors ([all 30](/agentkit/connectors/?category=monitoring)):

- [Microsoft Entra ID](/agentkit/connectors/microsoftentraid/): Scalekit connector, OAuth, 82 tools
- [Datadog](/agentkit/connectors/datadog/): Scalekit connector, API key, 105 tools
- [1Password](/agentkit/connectors/onepassword/): Scalekit connector, Access token, 4 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |