MCP tools reference

Fri, 09 Oct 2026 09:23:05 +0000

MCP tools reference

Use the table to confirm minimum Grafana RBAC permissions and scopes for each MCP tool. The sections after the table summarize RBAC patterns, optional categories, and a few operational notes.

Note
The tool list and behavior reflect the current server release. This page is not a roadmap or a commitment to future features.

What you’ll achieve

You can verify that a service account has the right permissions before you enable tools in production, and you can apply common scope patterns without rereading Grafana’s RBAC docs.

Before you begin

Grafana 9.0 or later for full API support.
Optional: a service account whose permissions match the tools you enable.

Review the tools table

The following table lists MCP tools, required RBAC permissions, and typical scopes. Categories marked with * are off until you add them to --enabled-tools (refer to Command-line flags).

Tool	Category	Description	Required RBAC Permissions	Required Scopes
`list_teams`	Admin*	List all teams	`teams:read`	`teams:*` or `teams:id:1`
`list_users_by_org`	Admin*	List users in an organization, with search and pagination	`users:read`	`global.users:*` or `global.users:id:123`
`list_all_roles`	Admin*	List all Grafana roles	`roles:read`	`roles:*`
`get_role_details`	Admin*	Get details for a Grafana role	`roles:read`	`roles:uid:editor`
`get_role_assignments`	Admin*	List assignments for a role	`roles:read`	`roles:uid:editor`
`list_user_roles`	Admin*	List roles for users	`roles:read`	`global.users:id:123`
`list_team_roles`	Admin*	List roles for teams	`roles:read`	`teams:id:7`
`get_resource_permissions`	Admin*	List permissions for a resource	`permissions:read`	`dashboards:uid:abcd1234`
`get_resource_description`	Admin*	Describe a Grafana resource type	`permissions:read`	`dashboards:*`
`user_info`	User	Current identity, capabilities, and accessible organizations	None (signed-in user)	—
`search_dashboards`	Search	Search for dashboards by query, folder UID, tag, or starred	`dashboards:read`	`dashboards:*` or `dashboards:uid:abc123`
`search_folders`	Search	Search for folders by query string	`folders:read`	`folders:*` or `folders:uid:xyz789`
`get_dashboard_by_uid`	Dashboard	Get a dashboard by uid, optionally a saved version	`dashboards:read`	`dashboards:uid:abc123`
`list_dashboard_versions`	Dashboard	List saved versions of a dashboard (version, author, time, message)	`dashboards:read`	`dashboards:uid:abc123`
`update_dashboard`	Dashboard	Update or create a new dashboard	`dashboards:create`, `dashboards:write`	`dashboards:`, `folders:` or `folders:uid:xyz789`
`get_dashboard_panel_queries`	Dashboard	Get panel title, queries, datasource UID and type from a dashboard	`dashboards:read`	`dashboards:uid:abc123`
`run_panel_query`	RunPanelQuery*	Execute one or more dashboard panel queries	`dashboards:read`, `datasources:query`	`dashboards:uid:`, `datasources:uid:`
`get_dashboard_property`	Dashboard	Extract specific parts of a dashboard using JSONPath expressions	`dashboards:read`	`dashboards:uid:abc123`
`get_dashboard_summary`	Dashboard	Get a compact summary of a dashboard without full JSON	`dashboards:read`	`dashboards:uid:abc123`
`create_folder`	Folder	Create a Grafana folder with a title and optional UID	`folders:create`	`folders:*`
`list_datasources`	Datasources	List datasources	`datasources:read`	`datasources:*`
`get_datasource`	Datasources	Get a datasource by UID or name	`datasources:read`	`datasources:uid:prometheus-uid`
`check_datasources_health`	Datasources	Check the health of one or more datasources	`datasources:query`, `datasources:read`	`datasources:uid:*`
`create_datasource`	Datasources	Create a datasource	`datasources:create`, `datasources:read`	`datasources:*`
`update_datasource`	Datasources	Update a datasource	`datasources:read`, `datasources:write`	`datasources:*` or `datasources:uid:abc123`
`get_query_examples`	Examples*	Get example queries for a datasource type	`datasources:read`	`datasources:*`
`query_prometheus`	Prometheus	Execute a query against a Prometheus datasource	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_metric_metadata`	Prometheus	List metric metadata	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_metric_names`	Prometheus	List available metric names	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_label_names`	Prometheus	List label names matching a selector	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_label_values`	Prometheus	List values for a specific label	`datasources:query`	`datasources:uid:prometheus-uid`
`query_prometheus_histogram`	Prometheus	Calculate histogram percentile values	`datasources:query`	`datasources:uid:prometheus-uid`
`list_incidents`	Incident	List incidents in Grafana Incident, optionally with their custom field values	Viewer role	N/A
`create_incident`	Incident	Create an incident in Grafana Incident, optionally setting custom fields	Editor role	N/A
`add_activity_to_incident`	Incident	Add an activity item to an incident in Grafana Incident	Editor role	N/A
`update_incident`	Incident	Update an incident in Grafana Incident (status, severity, title, or custom fields)	Editor role	N/A
`get_incident`	Incident	Get a single incident by ID, including its custom fields	Viewer role	N/A
`list_incident_custom_fields`	Incident	List the custom fields configured for incidents, with their types and select options	Viewer role	N/A
`query_loki_logs`	Loki	Query and retrieve logs using LogQL (either log or metric queries)	`datasources:query`	`datasources:uid:loki-uid`
`list_loki_label_names`	Loki	List all available label names in logs	`datasources:query`	`datasources:uid:loki-uid`
`list_loki_label_values`	Loki	List values for a specific log label	`datasources:query`	`datasources:uid:loki-uid`
`query_loki_stats`	Loki	Get statistics about log streams	`datasources:query`	`datasources:uid:loki-uid`
`query_loki_patterns`	Loki	Query detected log patterns to identify common structures	`datasources:query`	`datasources:uid:loki-uid`
`analyze_loki_labels`	Loki	Audit a Loki label strategy (live or static) and optionally diagnose query performance	`datasources:query`, `datasources:read`	`datasources:uid:loki-uid`
`suggest_loki_alloy_label_config`	Config	Generate an Alloy `loki.process` snippet enforcing approved labels	None	N/A
`query_influxdb`	InfluxDB*	Query InfluxDB using InfluxQL (v1) or Flux (v2)	`datasources:query`	`datasources:uid:influxdb-uid`
`query_graphite`	Graphite*	Query Graphite metrics	`datasources:query`, `datasources:read`	`datasources:uid:graphite-uid`
`list_graphite_metrics`	Graphite*	List Graphite metrics	`datasources:query`, `datasources:read`	`datasources:uid:graphite-uid`
`list_graphite_tags`	Graphite*	List Graphite tags	`datasources:query`, `datasources:read`	`datasources:uid:graphite-uid`
`query_graphite_density`	Graphite*	Query Graphite metric density	`datasources:query`, `datasources:read`	`datasources:uid:graphite-uid`
`list_sql_databases`	SQL*	List databases, schemas, or catalogs from a SQL datasource	`datasources:query`	`datasources:uid:*`
`list_sql_tables`	SQL*	List tables in a SQL datasource	`datasources:query`	`datasources:uid:*`
`describe_sql_table`	SQL*	Get column schema for a table	`datasources:query`	`datasources:uid:*`
`query_sql`	SQL*	Execute SQL queries with macro substitution	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_namespaces`	CloudWatch*	List available AWS CloudWatch namespaces	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_metrics`	CloudWatch*	List metrics in a namespace	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_dimensions`	CloudWatch*	List dimensions for a metric	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_dimension_values`	CloudWatch*	List values for a dimension key	`datasources:query`	`datasources:uid:*`
`query_cloudwatch`	CloudWatch*	Execute CloudWatch metric queries	`datasources:query`	`datasources:uid:*`
`list_cloud_logging_projects`	Cloud Logging*	List GCP projects readable by a Google Cloud Logging datasource	`datasources:query`	`datasources:uid:*`
`list_cloud_logging_buckets`	Cloud Logging*	List log buckets in a GCP project	`datasources:query`	`datasources:uid:*`
`list_cloud_logging_views`	Cloud Logging*	List log views in a log bucket	`datasources:query`	`datasources:uid:*`
`query_cloud_logging`	Cloud Logging*	Query logs with the Cloud Logging query language	`datasources:query`	`datasources:uid:*`
`query_elasticsearch`	Elasticsearch*	Query Elasticsearch using Lucene syntax or Query DSL	`datasources:query`	`datasources:uid:elasticsearch-uid`
`query_quickwit`	Quickwit*	Query Quickwit using Lucene syntax or Query DSL	`datasources:query`	`datasources:uid:quickwit-uid`
`alerting_rules_read`	Alerting	List and inspect alert rules (list, get, versions)	`alert.rules:read`	`folders:*` or `folders:uid:alerts-folder`
`alerting_rules_write`	Alerting	Create, update, and delete alert rules	`alert.rules:read` + `alert.rules:write`	`folders:*` or `folders:uid:alerts-folder`
`alerting_manage_routing`	Alerting	Manage notification policies, contact points, and time intervals	`alert.notifications:read`	Global scope
`alerting_routing_write`	Alerting	Create Grafana-managed contact points	`alert.notifications.provisioning:write`	Global scope
`alerting_silences_read`	Alerting	List and inspect alerting silences (list, get)	`alert.instances:read`	Global scope
`alerting_silences_write`	Alerting	Create, update, and expire alerting silences	`alert.instances:read` + `alert.instances:write`	Global scope
`list_oncall_schedules`	OnCall	List schedules from Grafana OnCall	`grafana-oncall-app.schedules:read`	Plugin-specific scopes
`get_oncall_shift`	OnCall	Get details for a specific OnCall shift	`grafana-oncall-app.schedules:read`	Plugin-specific scopes
`get_current_oncall_users`	OnCall	Get users currently on-call for a specific schedule	`grafana-oncall-app.schedules:read`	Plugin-specific scopes
`list_oncall_teams`	OnCall	List teams from Grafana OnCall	`grafana-oncall-app.user-settings:read`	Plugin-specific scopes
`list_oncall_users`	OnCall	List users from Grafana OnCall	`grafana-oncall-app.user-settings:read`	Plugin-specific scopes
`list_alert_groups`	OnCall	List alert groups from Grafana OnCall with filtering options	`grafana-oncall-app.alert-groups:read`	Plugin-specific scopes
`get_alert_group`	OnCall	Get a specific alert group from Grafana OnCall by its ID	`grafana-oncall-app.alert-groups:read`	Plugin-specific scopes
`update_alert_group`	OnCall	Acknowledge, unacknowledge, resolve, or unresolve an alert group	`grafana-oncall-app.alert-groups:write` (and `:read`)	Plugin-specific scopes
`list_pyroscope_label_names`	Pyroscope	List label names matching a selector	`datasources:query`	`datasources:uid:pyroscope-uid`
`list_pyroscope_label_values`	Pyroscope	List label values matching a selector for a label name	`datasources:query`	`datasources:uid:pyroscope-uid`
`list_pyroscope_profile_types`	Pyroscope	List available profile types	`datasources:query`	`datasources:uid:pyroscope-uid`
`query_pyroscope`	Pyroscope	Query profiles, metrics, or both from Pyroscope	`datasources:query`	`datasources:uid:pyroscope-uid`
`search_tempo_traces`	Tempo	Search for traces using TraceQL queries	`datasources:query`	`datasources:uid:tempo-uid`
`query_tempo_metrics`	Tempo	Compute trace-derived metrics (instant value or time series)	`datasources:query`	`datasources:uid:tempo-uid`
`get_tempo_trace`	Tempo	Fetch a complete trace by ID	`datasources:query`	`datasources:uid:tempo-uid`
`diff_tempo_traces`	Tempo	Compare two traces	`datasources:query`	`datasources:uid:tempo-uid`
`list_tempo_attribute_names`	Tempo	List available trace attribute names	`datasources:query`	`datasources:uid:tempo-uid`
`list_tempo_attribute_values`	Tempo	List values for a specific trace attribute	`datasources:query`	`datasources:uid:tempo-uid`
`get_tempo_traceql_docs`	Tempo	Retrieve TraceQL reference documentation with examples	`datasources:query`	`datasources:uid:tempo-uid`
`get_assertions`	Asserts	Get assertion summary for a given entity	Plugin-specific permissions	Plugin-specific scopes
`agento11y_manage_conversations`	Agent Observability*	List, search, and fetch LLM conversations from Grafana Agent Observability	`grafana-agento11y-app.conversations:read`	N/A
`agento11y_manage_generations`	Agent Observability*	Fetch LLM generation details and evaluation scores from Grafana Agent Observability	`grafana-agento11y-app.data:read`	N/A
`agento11y_manage_agents`	Agent Observability*	Read the agent catalog: list agents, get one agent version in full, list version history, and per-version score aggregates	`grafana-agento11y-app.data:read`	N/A
`agento11y_manage_evaluators`	Agent Observability*	Manage evaluators, evaluator templates, and the judge catalog (list, get, upsert, fork, test, delete)	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` for mutations and tests	N/A
`agento11y_manage_eval_rules`	Agent Observability*	Manage eval rules and guards (list, get, create, update, preview, delete)	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` for mutations and previews	N/A
`agento11y_manage_eval_collections`	Agent Observability*	Manage saved conversations and the collections that group them (list, get, save, create, update, delete, add and remove members)	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` for mutations	N/A
`agento11y_manage_experiments`	Agent Observability*	Read offline experiments, their trials, scores, artifact metadata, and filter facets; update and cancel an experiment	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` for mutations	N/A
`agento11y_manage_test_suites`	Agent Observability*	Manage the test suites that offline experiments run against, their versions, and their test cases (list, get, create, update, draft, publish, upsert, delete)	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` for mutations	N/A
`ask_assistant`	Assistant*	Send a prompt to Grafana Assistant and return the full text reply (multi-turn via `contextId`)	Plugin-specific permissions	Plugin-specific scopes
`generate_deeplink`	Navigation	Generate accurate deeplink URLs for Grafana resources	None (read-only URL generation)	N/A
`get_annotations`	Annotations	Fetch annotations with filters	`annotations:read`	`annotations:*` or `annotations:id:123`
`create_annotation`	Annotations	Create a new annotation (standard or Graphite format)	`annotations:write`	`annotations:*`
`update_annotation`	Annotations	Update specific fields of an annotation (partial update)	`annotations:write`	`annotations:*`
`delete_annotation`	Annotations	Delete an annotation by ID	`annotations:delete`	`annotations:*`
`get_annotation_tags`	Annotations	List annotation tags with optional filtering	`annotations:read`	`annotations:*`
`list_snapshots`	Snapshot	List dashboard snapshots with optional query and limit filters	`dashboards:read`	`dashboards:*` or `dashboards:uid:abc123`
`get_snapshot`	Snapshot	Get snapshot metadata and dashboard payload by snapshot key	`dashboards:read`	`dashboards:*` or `dashboards:uid:abc123`
`create_snapshot`	Snapshot	Create a dashboard snapshot from a full dashboard payload	`dashboards:write`	`dashboards:*` or `dashboards:uid:abc123`
`delete_snapshot`	Snapshot	Delete a dashboard snapshot by snapshot key	`dashboards:write`	`dashboards:*` or `dashboards:uid:abc123`
`get_panel_image`	Rendering	Render a stored dashboard or panel, a provisioning preview, or an ad-hoc Explore view as a PNG image	`dashboards:read`	`dashboards:uid:abc123`
`list_provisioning_repositories`	Provisioning	List provisioning repositories (e.g. git-sync sources) with their source URL, branch, sync state, and health	`provisioning.repositories:read`	N/A
`validate_provisioning_file`	Provisioning	Dry-run-apply a file from a provisioning repository and report admission validation errors	`provisioning.repositories:read`	N/A
`search_docs`	Docs	Search Grafana documentation or list product groups (omit query to list products)	None (public grafana.com/docs)	N/A
`get_doc`	Docs	Fetch a documentation page; set outline_only for headings, or section for bounded retrieval	None (public grafana.com/docs)	N/A
`get_plugin`	Plugins	Get an installed plugin	`plugins.app:access`	N/A
`search_plugin_information`	Plugins	Search the grafana.com plugin catalog	None	N/A
`install_plugin`	Plugins	Install a plugin	`plugins:install`	N/A
`grafana_api_request`	API	Call a Grafana HTTP API endpoint	None	Depends on the endpoint

* Categories marked with * are off until you add them to --enabled-tools.

Dashboard tools and context window

update_dashboard supports full JSON replacement and patch-style updates (uid plus operations). Prefer patches for small changes so you do not send large dashboard JSON to the model.

To limit context use when working with dashboards (issue #101):

Use get_dashboard_summary for an overview before edits.
Use get_dashboard_property with JSONPath when you only need part of a dashboard.
Avoid get_dashboard_by_uid unless you need the full dashboard JSON.

RBAC permissions

Each tool requires specific RBAC permissions. When you create a service account for the MCP server, grant the minimum actions for the tools you enable. You often need matching scopes as well (for example datasources:*, dashboards:*, folders:*).

Tip: If you want a faster setup instead of tuning many scopes, assign a built-in role such as Editor to the service account. Editor grants broad read and write access for most MCP operations; it is less granular than least privilege.

Grafana Incident tools use basic Grafana roles instead of fine-grained RBAC permissions:

Viewer: read-only operations (for example list incidents, get investigations).
Editor: write operations (for example create incidents, run analyses that modify state).

Refer to Grafana RBAC for full detail.

RBAC scopes

Scopes define which resources a permission applies to. You need the right permission and scope together.

Broad access (organization-wide) often uses * wildcards:

datasources:*
dashboards:*
folders:*
teams:*

Limited access uses specific UIDs or IDs:

datasources:uid:prometheus-uid
dashboards:uid:abc123
folders:uid:xyz789
teams:id:5
global.users:id:123

Examples:

Full MCP access (typical broad grants):

datasources:* (datasources:read, datasources:query)
dashboards:* (dashboards:read, dashboards:create, dashboards:write)
folders:* (for dashboard creation and alert rules)
teams:* (teams:read)
global.users:* (users:read)

Limited datasource access (only specific Prometheus and Loki instances):

datasources:uid:prometheus-prod (datasources:query)
datasources:uid:loki-prod (datasources:query)

Dashboard-only read access:

dashboards:uid:monitoring-dashboard (dashboards:read)
dashboards:uid:alerts-dashboard (dashboards:read)

Enable or disable tools

You can limit which tools the server exposes with --enabled-tools, --disable-<category>, --disable-write, --disable-query, and --enable-query. Refer to Enable and disable tools and Command-line flags.

Panel and dashboard images

get_panel_image needs the Grafana Image Renderer service installed and configured in Grafana.

Reference on Grafana Labs

MCP tools reference

MCP tools reference

What you’ll achieve

Before you begin

Review the tools table

Dashboard tools and context window

RBAC permissions

RBAC scopes

Enable or disable tools

Panel and dashboard images

Next steps