--- title: "MCP tools reference | Grafana documentation" description: "MCP tools, required Grafana RBAC permissions and scopes, and related guidance." --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # 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](/docs/grafana/latest/administration/service-accounts/#add-a-token-to-a-service-account-in-grafana) 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](../../configure/command-line-flags/)). Expand table | 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](https://github.com/grafana/mcp-grafana/issues/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](/docs/grafana/latest/administration/roles-and-permissions/access-control/) 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): ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```none 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): ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```none datasources:uid:prometheus-prod (datasources:query) datasources:uid:loki-prod (datasources:query) ``` Dashboard-only read access: ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```none 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-`, `--disable-write`, `--disable-query`, and `--enable-query`. Refer to [Enable and disable tools](../../configure/enable-and-disable-tools/) and [Command-line flags](../../configure/command-line-flags/). ## Panel and dashboard images `get_panel_image` needs the [Grafana Image Renderer](/docs/grafana/latest/setup-grafana/image-rendering/) service installed and configured in Grafana. ## Next steps - [Command-line flags](../../configure/command-line-flags/) - [Enable and disable tools](../../configure/enable-and-disable-tools/) - [Introduction](../../introduction/)