MCP 도구 레퍼런스
MCP 도구 레퍼런스
각 MCP 도구에 필요한 최소 Grafana RBAC 권한과 스코프를 표로 정리해 둔 문서예요. 표 아래 섹션에서는 RBAC 패턴, 선택형 카테고리, 운영상 참고할 점을 요약해 드릴게요.
출처: 문서
본문
도구 목록과 동작 방식은 현재 서버 릴리스를 기준으로 해요. 이 페이지는 로드맵이나 향후 기능에 대한 약속이 아니에요.
무엇을 얻을 수 있을까요
도구를 프로덕션에서 활성화하기 전에 서비스 계정이 올바른 권한을 갖췄는지 확인할 수 있고, Grafana의 RBAC 문서를 다시 읽지 않아도 흔한 스코프 패턴을 적용할 수 있어요.
시작하기 전에
- 전체 API 지원을 위해 Grafana 9.0 이상이 필요해요.
- 선택 사항: 활성화한 도구의 권한과 일치하는 서비스 계정.
도구 표 살펴보기
아래 표는 MCP 도구, 필요한 RBAC 권한, 일반적인 스코프를 보여줘요. * 표시가 붙은 카테고리는 --enabled-tools에 추가할 때까지 꺼져 있어요 (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 all users in an organization | 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 |
| 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 |
| query_influxdb | InfluxDB* | Query InfluxDB using InfluxQL (v1) or Flux (v2) | datasources:query | datasources:uid:influxdb-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_manage_rules | Alerting | Manage alert rules (list, get, versions, create, update, delete) | alert.rules:read + alert.rules:write for mutations | folders:* or folders:uid:alerts-folder |
| alerting_manage_routing | Alerting | Manage notification policies, contact points, and time intervals | alert.notifications:read | Global scope |
| alerting_manage_silences | Alerting | Manage alerting silences (list, get, create, update, expire) | alert.instances:read + alert.instances:write for mutations | 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 |
| get_sift_investigation | Sift | Retrieve an existing Sift investigation by its UUID | Viewer role | N/A |
| get_sift_analysis | Sift | Retrieve a specific analysis from a Sift investigation | Viewer role | N/A |
| list_sift_investigations | Sift | Retrieve a list of Sift investigations with an optional limit | Viewer role | N/A |
| find_error_pattern_logs | Sift | Finds elevated error patterns in Loki logs. | Editor role | N/A |
| find_slow_requests | Sift | Finds slow requests from the relevant tempo datasources. | Editor role | N/A |
| 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 — or a provisioning preview from a repository branch — 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 |
*표시가 붙은 카테고리는--enabled-tools에 추가할 때까지 꺼져 있어요.
대시보드 도구와 컨텍스트 윈도
update_dashboard는 전체 JSON 교체와 패치 스타일 업데이트(uid + 연산)를 모두 지원해요. 작은 변경이라면 패치를 쓰는 게 좋아요. 그래야 큰 대시보드 JSON을 모델에 보내지 않으니까요.
대시보드를 다룰 때 컨텍스트 사용량을 줄이려면 (issue #101):
- 편집하기 전 개요는
get_dashboard_summary로 확인하세요. - 대시보드의 일부만 필요하다면
get_dashboard_property에 JSONPath를 쓰세요. - 전체 대시보드 JSON이 꼭 필요할 때만
get_dashboard_by_uid를 쓰세요.
RBAC 권한
각 도구는 특정 RBAC 권한을 요구해요. MCP 서버용 서비스 계정을 만들 때, 활성화한 도구에 필요한 최소한의 액션을 부여하세요. 대개 일치하는 스코프도 함께 필요해요 (예: datasources:*, dashboards:*, folders:*).
팁: 여러 스코프를 세밀하게 조정하는 대신 빠른 구성을 원한다면 서비스 계정에 Editor 같은 내장 역할을 할당하세요. Editor는 대부분의 MCP 작업에 폭넓은 읽기·쓰기 권한을 주지만, 최소 권한만큼 세밀하지는 않아요.
Grafana Incident와 Sift 도구는 세밀한 RBAC 권한 대신 기본 Grafana 역할을 사용해요:
- Viewer: 읽기 전용 작업 (예: 인시던트 목록 조회, 조사 조회).
- Editor: 쓰기 작업 (예: 인시던트 생성, 상태를 변경하는 분석 실행).
자세한 내용은 Grafana RBAC를 참고하세요.
RBAC 스코프
스코프는 권한이 적용되는 리소스 범위를 정의해요. 올바른 권한과 스코프가 함께 있어야 해요.
광범위한 접근(조직 전체)은 흔히 * 와일드카드를 사용해요:
datasources:*dashboards:*folders:*teams:*
제한적 접근은 특정 UID나 ID를 사용해요:
datasources:uid:prometheus-uiddashboards:uid:abc123folders:uid:xyz789teams:id:5global.users:id:123
예시:
전체 MCP 접근 (일반적인 광범위한 부여):
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)
제한된 데이터소스 접근 (특정 Prometheus와 Loki 인스턴스만):
datasources:uid:prometheus-prod (datasources:query)
datasources:uid:loki-prod (datasources:query)
대시보드 전용 읽기 접근:
dashboards:uid:monitoring-dashboard (dashboards:read)
dashboards:uid:alerts-dashboard (dashboards:read)
도구 활성화/비활성화
서버가 노출하는 도구는 --enabled-tools, --disable-, --disable-write, --disable-query, --enable-query로 제한할 수 있어요. Enable and disable tools 와 Command-line flags 문서를 참고하세요.
패널 및 대시보드 이미지
get_panel_image는 Grafana에 Grafana Image Renderer 서비스가 설치·구성되어 있어야 해요.
다음 단계
- Command-line flags
- Enable and disable tools
- Introduction