Grafana

resmi

Cari dasbor, selidiki insiden, dan kueri sumber data di instance Grafana Anda

GitHub

3.5k

Coba MCP iniDisponsori

Apa yang bisa Anda lakukan dengan Grafana MCP?

Cari dan periksa dasbor — Minta dasbor berdasarkan judul, folder, tag, atau status bintang, lalu ambil ringkasan, versi, atau properti JSONPath tertentu seperti $.title melalui search_dashboards, get_dashboard_summary, atau get_dashboard_property.
Kueri Prometheus dan Loki — Jalankan kueri PromQL atau LogQL, ambil metadata metrik/label, dan hitung persentil histogram (p50–p99) langsung dari sumber data Anda.
Kelola alerting dan insiden — Daftarkan atau buat aturan alert, periksa status pemicu, dan cari atau perbarui catatan Insiden Grafana dengan kolom kustom.
Jelajahi data SQL dan CloudWatch — Daftarkan tabel, deskripsikan skema, dan jalankan SQL dengan makro di ClickHouse, Snowflake, Athena, MySQL, PostgreSQL, atau MSSQL; juga kueri metrik CloudWatch berdasarkan namespace dan dimensi.
Render dasbor dan buat tautan — Dapatkan panel atau dasbor sebagai gambar PNG, atau buat tautan mendalam yang akurat ke dasbor, panel, dan Explore dengan rentang waktu dan variabel.

Dokumentasi

Server MCP Grafana

Sebuah server Model Context Protocol (MCP) untuk Grafana.

Ini menyediakan akses ke instance Grafana Anda dan ekosistem di sekitarnya.

Memulai dengan Cepat

Membutuhkan uv. Tambahkan berikut ini ke konfigurasi klien MCP Anda (misalnya Claude Desktop, Cursor):

{
  "mcpServers": {
    "grafana": {
      "command": "uvx",
      "args": ["mcp-grafana"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

Untuk Grafana Cloud, ganti GRAFANA_URL dengan URL instance Anda (misalnya https://myinstance.grafana.net). Lihat Penggunaan untuk opsi instalasi lainnya termasuk Docker, biner, dan Helm.

Persyaratan

Grafana versi 9.0 atau lebih baru diperlukan untuk fungsionalitas penuh. Beberapa fitur, terutama operasi terkait sumber data, mungkin tidak berfungsi dengan benar pada versi sebelumnya karena titik akhir API yang hilang.

Fitur

Fitur-fitur berikut saat ini tersedia di server MCP. Daftar ini hanya untuk tujuan informasi dan tidak mewakili peta jalan atau komitmen terhadap fitur masa depan.

Dasbor

Cari dasbor: Temukan dasbor berdasarkan judul, UID folder, tag, atau status berbintang
Dapatkan dasbor berdasarkan UID: Ambil detail dasbor lengkap menggunakan pengidentifikasi uniknya. Berikan opsional version untuk memuat snapshot yang disimpan alih-alih dasbor saat ini. Peringatan: Dasbor besar dapat menghabiskan ruang konteks yang signifikan.
Daftar versi dasbor: Daftar versi dasbor yang disimpan sebagai metadata ringkas (nomor versi, penulis, stempel waktu, pesan simpan)
Dapatkan ringkasan dasbor: Dapatkan gambaran ringkas dasbor termasuk judul, jumlah panel, jenis panel, variabel, dan metadata tanpa JSON lengkap untuk meminimalkan penggunaan ruang konteks
Dapatkan properti dasbor: Ekstrak bagian tertentu dari dasbor menggunakan ekspresi JSONPath (misalnya $.title, $.panels[*].title) untuk mengambil hanya data yang diperlukan dan mengurangi konsumsi ruang konteks
Perbarui atau buat dasbor: Ubah dasbor yang ada atau buat yang baru. Peringatan: Membutuhkan JSON dasbor lengkap yang dapat menghabiskan banyak ruang konteks.
Patch dasbor: Terapkan perubahan spesifik pada dasbor tanpa memerlukan JSON lengkap, secara signifikan mengurangi penggunaan ruang konteks untuk modifikasi yang ditargetkan
Dapatkan kueri panel dan info sumber data: Dapatkan judul, string kueri, dan informasi sumber data (termasuk UID dan jenis, jika tersedia) dari setiap panel di dasbor

Jalankan Kueri Panel

Catatan: Alat jalankan kueri panel dinonaktifkan secara default. Untuk mengaktifkannya, tambahkan runpanelquery ke flag --enabled-tools Anda.

Jalankan kueri panel: Jalankan kueri panel dasbor dengan rentang waktu kustom dan penggantian variabel.

Manajemen Ruang Konteks

Alat dasbor sekarang menyertakan beberapa strategi untuk mengelola penggunaan ruang konteks secara efektif (masalah #101):

Gunakan get_dashboard_summary untuk gambaran dasbor dan perencanaan modifikasi
Gunakan get_dashboard_property dengan JSONPath ketika Anda hanya membutuhkan bagian dasbor tertentu
Hindari get_dashboard_by_uid kecuali Anda secara khusus membutuhkan JSON dasbor lengkap

Sumber Data

Daftar dan ambil informasi sumber data: Lihat semua sumber data yang dikonfigurasi dan ambil informasi terperinci tentang masing-masing.
- Jenis sumber data yang didukung: Prometheus, Loki, ClickHouse, CloudWatch, Elasticsearch, OpenSearch, Snowflake, Athena.

Contoh Kueri

Catatan: Alat contoh kueri dinonaktifkan secara default. Untuk mengaktifkannya, tambahkan examples ke flag --enabled-tools Anda.

Dapatkan contoh kueri: Ambil contoh kueri untuk berbagai jenis sumber data untuk mempelajari sintaks kueri.

Kueri Prometheus

Kueri Prometheus: Jalankan kueri PromQL (mendukung kueri metrik instan dan rentang) terhadap sumber data Prometheus.
Kueri metadata Prometheus: Ambil metadata metrik, nama metrik, nama label, dan nilai label dari sumber data Prometheus.
Kueri persentil histogram: Hitung nilai persentil histogram (p50, p90, p95, p99) menggunakan histogram_quantile.

Kueri Loki

Kueri log dan metrik Loki: Jalankan kueri log dan kueri metrik menggunakan LogQL terhadap sumber data Loki.
Kueri metadata Loki: Ambil nama label, nilai label, dan statistik aliran dari sumber data Loki.
Kueri pola Loki: Ambil pola log yang terdeteksi oleh Loki untuk mengidentifikasi struktur log umum dan anomali.

Kueri InfluxDB

Catatan: Alat InfluxDB dinonaktifkan secara default. Untuk mengaktifkannya, tambahkan influxdb ke flag --enabled-tools Anda.

Kueri InfluxDB: Jalankan kueri terhadap sumber data InfluxDB menggunakan InfluxQL (v1.x) atau Flux (v2.x). Dialek disimpulkan dari konfigurasi sumber data, atau dapat diatur secara eksplisit melalui parameter dialect.

Kueri Sumber Data SQL

Catatan: Alat SQL dinonaktifkan secara default. Untuk mengaktifkannya, tambahkan sql ke flag --enabled-tools Anda. Alias kompatibilitas mundur clickhouse, snowflake, dan athena juga berfungsi.

Alat SQL terpadu mendukung ClickHouse, Snowflake, Athena, MySQL, PostgreSQL, dan MSSQL melalui satu set alat. Kueri melalui plugin sumber data Grafana, sehingga autentikasi ditangani oleh konfigurasi sumber data — kredensial tidak pernah terlihat oleh server MCP.

Daftar database/skema/katalog: Temukan unit organisasi untuk sumber data SQL. Untuk Athena, hapus katalog untuk mendaftar katalog, atau berikan katalog untuk mendaftar database.
Daftar tabel: Daftar tabel dalam database atau skema dengan metadata (jumlah baris, ukuran jika tersedia).
Jelaskan skema tabel: Dapatkan nama kolom, jenis, nullability, default, dan komentar.
Kueri SQL: Jalankan kueri SQL dengan substitusi makro khusus sumber data ($__timeFilter(col), $__from/$__to, $__interval, ${varname}), penegakan batas otomatis, dan dukungan variabel template.

Kueri CloudWatch

Catatan: Alat CloudWatch dinonaktifkan secara default. Untuk mengaktifkannya, tambahkan cloudwatch ke flag --enabled-tools Anda.

Daftar namespace CloudWatch: Temukan namespace AWS CloudWatch yang tersedia.
Daftar metrik CloudWatch: Daftar metrik yang tersedia dalam namespace tertentu.
Daftar dimensi CloudWatch: Dapatkan dimensi untuk memfilter kueri metrik.
Kueri CloudWatch: Jalankan kueri metrik CloudWatch dengan dukungan rentang waktu.

Kueri Google Cloud Logging

Catatan: Alat Google Cloud Logging dinonaktifkan secara default. Untuk mengaktifkannya, tambahkan cloudlogging ke flag --enabled-tools Anda. Membutuhkan plugin sumber data Google Cloud Logging (googlecloud-logging-datasource) versi 1.8.0 atau lebih baru, yang membutuhkan Grafana 11.2+. Versi plugin yang lebih lama mengembalikan tata letak respons yang berbeda dan query_cloud_logging melaporkan kesalahan yang meminta peningkatan.

Daftar proyek Cloud Logging: Temukan ID proyek GCP yang dapat dibaca lognya oleh sumber data.
Daftar bucket dan tampilan Cloud Logging: Temukan bucket log dan tampilan log untuk membatasi kueri.
Kueri Cloud Logging: Jalankan filter bahasa kueri Cloud Logging (misalnya resource.type="k8s_container" AND severity>=ERROR) dengan rentang waktu dan batas; mengembalikan entri terbaru-pertama dengan tingkat keparahan, isi, label, dan ID jejak. Autentikasi GCP ditangani oleh konfigurasi sumber data.

Kueri Graphite

Catatan: Alat Graphite dinonaktifkan secara default. Untuk mengaktifkannya, tambahkan graphite ke flag --enabled-tools Anda.

Kueri Graphite: Jalankan kueri API render Graphite terhadap sumber data Graphite.
Daftar metrik Graphite: Jelajahi dan temukan jalur metrik Graphite.
Daftar tag Graphite: Daftar tag Graphite yang tersedia dan nilai tag.
Kueri kepadatan Graphite: Kueri kepadatan metrik Graphite untuk pola tertentu.

Kueri Elasticsearch/OpenSearch

Catatan: Alat Elasticsearch/OpenSearch dinonaktifkan secara default. Untuk mengaktifkannya, tambahkan elasticsearch ke flag --enabled-tools Anda.

Kueri Elasticsearch/OpenSearch: Jalankan kueri pencarian terhadap sumber data Elasticsearch atau OpenSearch menggunakan sintaks kueri Lucene atau Elasticsearch Query DSL. Mendukung pemfilteran berdasarkan rentang waktu dan mengambil log, metrik, atau data terindeks lainnya. Mengembalikan dokumen dengan indeks, ID, bidang sumber, dan skor relevansi opsional.

Kueri Quickwit

Catatan: Alat Quickwit dinonaktifkan secara default. Untuk mengaktifkannya, tambahkan quickwit ke flag --enabled-tools Anda.

Kueri Quickwit: Jalankan kueri pencarian terhadap sumber data Quickwit menggunakan sintaks kueri Lucene atau sebagian Elasticsearch Query DSL yang kompatibel. Mendukung pemfilteran berdasarkan rentang waktu dan mengambil log atau dokumen terindeks lainnya. Mengembalikan dokumen dengan indeks, ID, bidang sumber, dan skor relevansi opsional.

Observabilitas Agen

Catatan: Alat Observabilitas Agen dinonaktifkan secara default dan hanya berfungsi di Grafana Cloud. Untuk mengaktifkannya, tambahkan agento11y ke flag --enabled-tools Anda.

Mencantumkan dan mencari percakapan: Mencantumkan percakapan LLM terbaru atau mencarinya dengan ekspresi filter (model, penyedia, agen, status, jenis kesalahan, hasil evaluasi, dan lainnya) dalam rentang waktu tertentu. Hasil pencarian mencakup jumlah kesalahan, ringkasan peringkat, ringkasan evaluasi, dan ID jejak.
Mendapatkan detail percakapan: Mengambil satu percakapan dengan semua generasinya, termasuk prompt dan output.
Mendapatkan detail generasi dan skor: Mengambil satu generasi berdasarkan ID, beserta skor evaluasinya (evaluator, kunci skor, nilai, lulus, penjelasan).
Membaca katalog agen: Mencantumkan agen yang mengirim telemetri, mengambil satu versi agen secara lengkap (prompt sistem lengkap, setiap alat dengan skema JSON-nya, dan model yang dijalankannya), menelusuri riwayat versi agen, dan membandingkan agregat skor evaluasi per versi. Versi efektif adalah hash sha256: yang tidak pernah terpengaruh oleh perubahan alat; untuk agen yang tidak melaporkan versinya sendiri, hash tersebut dihasilkan dari prompt sistem, sehingga pengeditan prompt menghasilkan versi baru. Baris katalog dan versi membawa token_estimate, yang layak diperiksa sebelum mengambil prompt lengkap.
Memeriksa evaluator dan templat: Membaca evaluator tempat skor berasal, templat yang menjadi asalnya, serta penyedia juri dan model yang tersedia untuk evaluator juri LLM. Dengan alat tulis diaktifkan, juga dapat membuat, menggandakan, menguji, dan menghapus evaluator.
Memeriksa aturan eval dan penjaga: Membaca aturan eval asinkron yang mengikat evaluator ke lalu lintas produksi, serta penjaga (aturan hook) yang berjalan inline dan dapat memperingatkan atau menolak. Dengan alat tulis diaktifkan, juga dapat membuat, memperbarui, mempratinjau, dan menghapusnya. Operasi tulis serta operasi non-persisten preview_rule dan test_evaluator memerlukan izin grafana-agento11y-app.eval:write, yang diberikan oleh peran Admin Agento11y.
Mengkurasi percakapan dan koleksi tersimpan: Membaca percakapan tersimpan (penanda yang memberikan ID, nama, dan tag stabil pada percakapan) serta koleksi yang mengelompokkannya, termasuk jumlah anggota setiap koleksi dan koleksi yang tertanam di setiap baris percakapan tersimpan. Dengan alat tulis diaktifkan, juga dapat menandai percakapan, membuat dan mengedit koleksi, serta menambah atau menghapus anggota. Operasi tulis ini memerlukan izin grafana-agento11y-app.eval:write yang sama.
Membaca dan mengedit rangkaian pengujian: Mencantumkan rangkaian pengujian berversi yang digunakan untuk eksperimen offline, membaca satu rangkaian dengan riwayat versi lengkapnya, dan menelusuri kasus pengujian dari sebuah versi. Dengan alat tulis diaktifkan, juga dapat membuat rangkaian, mengganti nama atau menandainya ulang, membuka versi draf, menerbitkannya, serta menulis atau menghapus kasus pengujiannya. Versi yang diterbitkan dibekukan, sehingga pengeditan berarti membuka draf baru. Operasi tulis ini memerlukan grafana-agento11y-app.eval:write.
Membaca eksperimen offline: Mencantumkan proses evaluasi atas rangkaian pengujian dan membaca satu proses dengan tingkat kelulusan utama, biaya, dan total token. Menelusuri laporan per kasus pengujian hingga percobaan, skornya dengan penjelasan setiap juri, dan metadata artefaknya. Dengan alat tulis diaktifkan, juga dapat mengganti nama atau menandai ulang eksperimen serta membatalkan eksperimen yang berjalan, yang memerlukan grafana-agento11y-app.eval:write. Eksperimen dibuat oleh runner SDK, bukan oleh alat ini.

Asisten Grafana

Catatan: Alat Asisten dinonaktifkan secara default dan memerlukan plugin Asisten Grafana (grafana-assistant-app) untuk diinstal pada instance Grafana target. Alat-alat ini juga merupakan alat tulis (asisten dapat mengubah status stack), sehingga dilewati saat --disable-write diatur. Untuk mengaktifkannya, tambahkan assistant ke flag --enabled-tools Anda.

Tanyakan asisten: Kirim prompt bahasa alami ke Asisten Grafana dan tunggu balasan teks lengkap. Asisten dapat menggunakan alat, metrik, log, dan konteks stack lainnya—lebih luas daripada menjalankan satu kueri sumber data yang terisolasi. Teruskan contextId yang dikembalikan dalam panggilan lanjutan untuk melanjutkan percakapan yang sama. Tugas yang kompleks dapat memakan waktu beberapa menit; panggilan memblokir hingga balasan selesai atau permintaan habis waktu (5 menit).

Insiden

Cari, buat, dan perbarui insiden: Kelola insiden di Grafana Incident, termasuk mencari, membuat, menambahkan aktivitas, serta membaca atau mengatur bidang kustom.

Investigasi Sift

Cantumkan investigasi Sift: Ambil daftar investigasi Sift, dengan dukungan parameter batas.
Dapatkan investigasi Sift: Ambil detail investigasi Sift tertentu berdasarkan UUID-nya.
Dapatkan analisis Sift: Ambil analisis tertentu dari investigasi Sift.
Temukan pola kesalahan dalam log: Deteksi pola kesalahan yang meningkat dalam log Loki menggunakan Sift.
Temukan permintaan lambat: Deteksi permintaan lambat menggunakan Sift (Tempo).

Alerting

Cantumkan dan ambil informasi aturan alert: Lihat aturan alert dan statusnya (firing/normal/error/dll.) di Grafana. Mendukung aturan yang dikelola Grafana dan aturan yang dikelola sumber data dari sumber data Prometheus atau Loki.
Buat dan perbarui aturan alert: Buat aturan alert baru atau ubah yang sudah ada.
Hapus aturan alert: Hapus aturan alert berdasarkan UID.
Kelola perutean alerting: Lihat kebijakan notifikasi, titik kontak, dan interval waktu. Mendukung titik kontak yang dikelola Grafana dan penerima dari sumber data Alertmanager eksternal (Prometheus Alertmanager, Mimir, Cortex).

Grafana OnCall

Cantumkan dan kelola jadwal: Lihat dan kelola jadwal on-call di Grafana OnCall.
Dapatkan detail shift: Ambil informasi terperinci tentang shift on-call tertentu.
Dapatkan pengguna on-call saat ini: Lihat pengguna yang sedang on-call untuk sebuah jadwal.
Cantumkan tim dan pengguna: Lihat semua tim dan pengguna OnCall.
Cantumkan grup alert: Lihat dan filter grup alert dari Grafana OnCall berdasarkan berbagai kriteria termasuk status, integrasi, label, dan rentang waktu.
Dapatkan detail grup alert: Ambil informasi terperinci tentang grup alert tertentu berdasarkan ID-nya.

Admin

Catatan: Alat Admin dinonaktifkan secara default. Untuk mengaktifkannya, sertakan admin dalam flag --enabled-tools Anda.

Cantumkan tim: Lihat semua tim yang dikonfigurasi di Grafana.
Cantumkan pengguna: Lihat semua pengguna dalam sebuah organisasi di Grafana.
Cantumkan semua peran: Cantumkan semua peran Grafana, dengan filter opsional untuk peran yang dapat didelegasikan.
Dapatkan detail peran: Dapatkan detail untuk peran Grafana tertentu berdasarkan UID.
Cantumkan penugasan untuk sebuah peran: Cantumkan semua pengguna, tim, dan akun layanan yang ditugaskan ke sebuah peran.
Cantumkan peran untuk pengguna: Cantumkan semua peran yang ditugaskan ke satu atau lebih pengguna.
Cantumkan peran untuk tim: Cantumkan semua peran yang ditugaskan ke satu atau lebih tim.
Cantumkan izin untuk sebuah sumber daya: Cantumkan semua izin yang ditentukan untuk sumber daya tertentu (dashboard, sumber data, folder, dll.).
Jelaskan sumber daya Grafana: Cantumkan izin yang tersedia dan kemampuan penugasan untuk sebuah jenis sumber daya.

Pengguna

Info pengguna: Dapatkan identitas Grafana saat ini — login, email, nama, apakah admin Grafana (server), organisasi saat ini, dan organisasi yang dapat diakses kredensial (dengan peran). Gunakan untuk menemukan nilai orgId yang valid untuk permintaan multi-organisasi.

Navigasi

Hasilkan tautan dalam: Buat URL tautan dalam yang akurat untuk sumber daya Grafana alih-alih mengandalkan tebakan URL LLM.
- Tautan dashboard: Buat tautan langsung ke dashboard menggunakan UID-nya (mis., http://localhost:3000/d/dashboard-uid)
- Tautan panel: Buat tautan ke panel tertentu dalam dashboard dengan parameter viewPanel (mis., http://localhost:3000/d/dashboard-uid?viewPanel=5)
- Tautan Jelajah: Buat tautan ke Grafana Explore dengan sumber data yang telah dikonfigurasi (mis., http://localhost:3000/explore?schemaVersion=1&panes={"a":{"datasource":"prometheus-uid"}}). Grafana di bawah 10.2 tidak memahami panes, sehingga format lama ?left={...} dikeluarkan untuk versi tersebut.
- Dukungan rentang waktu: Tambahkan parameter rentang waktu ke tautan (from=now-1h&to=now)
- Parameter kustom: Sertakan parameter kueri tambahan seperti variabel dashboard atau interval penyegaran

Anotasi

Dapatkan Anotasi: Kueri anotasi dengan filter. Mendukung rentang waktu, UID dashboard, tag, dan mode pencocokan.
Buat Anotasi: Buat anotasi baru pada dashboard atau panel.
Buat Anotasi Graphite: Buat anotasi menggunakan format Graphite (what, when, tags, data).
Perbarui Anotasi: Ganti semua bidang anotasi yang ada (pembaruan penuh).
Patch Anotasi: Perbarui hanya bidang tertentu dari anotasi (pembaruan parsial).
Hapus Anotasi: Hapus anotasi secara permanen berdasarkan ID.
Dapatkan Tag Anotasi: Cantumkan tag anotasi yang tersedia dengan filter opsional.

Snapshot

Cantumkan snapshot: Cantumkan snapshot dashboard dengan filter kueri dan batas opsional.
Dapatkan snapshot: Ambil metadata snapshot dan payload dashboard berdasarkan kunci snapshot.
Buat snapshot: Buat snapshot dashboard dari payload dashboard lengkap, dengan opsi kedaluwarsa dan snapshot eksternal opsional.
Hapus snapshot: Hapus snapshot berdasarkan kunci snapshot.

Rendering

Dapatkan gambar panel atau dashboard: Render panel dashboard Grafana atau dashboard lengkap sebagai gambar PNG. Mengembalikan gambar sebagai data berenkode base64 untuk digunakan dalam laporan, alert, atau presentasi. Mendukung penyesuaian dimensi, rentang waktu, tema, skala, dan variabel dashboard. Juga mendukung rendering dashboard yang belum diterapkan dari cabang repositori provisioning (mis., pratinjau PR git-sync) melalui parameter opsional provisioningPreview.
- Catatan: Memerlukan layanan Grafana Image Renderer untuk diinstal dan dikonfigurasi.

Provisioning

Cantumkan repositori provisioning: Cantumkan repositori provisioning yang dikonfigurasi untuk instance Grafana ini (mis., sumber git-sync), mengembalikan slug setiap repositori beserta URL sumber, cabang, jalur, status sinkronisasi, dan kesehatannya.
Validasi file provisioning: Terapkan kering file dari repositori provisioning pada cabang atau commit tertentu. Mengembalikan apakah akan diterima, tindakan sumber daya (buat/perbarui), jenis sumber daya target, dan kesalahan validasi terstruktur — permukaan penerimaan yang sama yang digunakan komentator PR Grafana.

Daftar alat dapat dikonfigurasi, sehingga Anda dapat memilih alat mana yang ingin tersedia untuk klien MCP. Ini berguna jika Anda tidak menggunakan fungsionalitas tertentu atau tidak ingin menghabiskan terlalu banyak ruang di jendela konteks. Untuk menonaktifkan kategori alat, gunakan flag --disable-<category> saat memulai server. Misalnya, untuk menonaktifkan alat OnCall, gunakan --disable-oncall, atau untuk menonaktifkan pembuatan tautan dalam navigasi, gunakan --disable-navigation.

Izin RBAC

Setiap alat memerlukan izin RBAC tertentu agar berfungsi dengan benar. Saat membuat akun layanan untuk server MCP, pastikan akun tersebut memiliki izin yang diperlukan berdasarkan alat yang Anda rencanakan untuk digunakan. Izin yang tercantum adalah tindakan minimum yang diperlukan — Anda mungkin juga memerlukan cakupan yang sesuai (mis., datasources:*, dashboards:*, folders:*) tergantung pada kasus penggunaan Anda.

Tip: Jika Anda tidak terbiasa dengan RBAC Grafana atau menginginkan pengaturan yang lebih cepat dan sederhana daripada mengonfigurasi banyak cakupan granular, Anda dapat menetapkan peran bawaan seperti Editor ke akun layanan. Peran Editor memberikan akses baca/tulis yang luas yang akan memungkinkan sebagian besar operasi server MCP; peran ini kurang granular (dan karenanya kurang ketat) daripada cakupan yang diterapkan secara manual, jadi gunakan hanya ketika kenyamanan lebih penting daripada akses hak istimewa minimum yang ketat.

Catatan: Alat Grafana Incident dan Sift menggunakan peran Grafana dasar alih-alih izin RBAC yang terperinci:

Peran Viewer: Diperlukan untuk operasi baca-saja (cantumkan insiden, dapatkan investigasi)
Peran Editor: Diperlukan untuk operasi tulis (buat insiden, ubah investigasi)

Untuk informasi lebih lanjut tentang RBAC Grafana, lihat dokumentasi resmi.

Cakupan RBAC

Cakupan mendefinisikan sumber daya spesifik yang berlaku untuk izin. Setiap tindakan memerlukan kombinasi izin dan cakupan yang sesuai.

Pola Cakupan Umum:

Akses luas: Gunakan wildcard * untuk akses di seluruh organisasi
- datasources:* - Akses ke semua sumber data
- dashboards:* - Akses ke semua dasbor
- folders:* - Akses ke semua folder
- teams:* - Akses ke semua tim
Akses terbatas: Gunakan UID atau ID tertentu untuk membatasi akses ke sumber daya individual
- datasources:uid:prometheus-uid - Akses hanya ke sumber data Prometheus tertentu
- dashboards:uid:abc123 - Akses hanya ke dasbor dengan UID abc123
- folders:uid:xyz789 - Akses hanya ke folder dengan UID xyz789
- teams:id:5 - Akses hanya ke tim dengan ID 5
- global.users:id:123 - Akses hanya ke pengguna dengan ID 123

Contoh:

Akses penuh server MCP: Berikan izin luas untuk semua alat

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)

Akses sumber data terbatas: Hanya kueri instance Prometheus dan Loki tertentu

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

Akses khusus dasbor: Baca hanya dasbor tertentu

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

Alat

Tool	Kategori	Deskripsi	Izin RBAC yang Diperlukan	Scope yang Diperlukan
`list_teams`	Admin	Menampilkan semua tim	`teams:read`	`teams:*` atau `teams:id:1`
`list_users_by_org`	Admin	Menampilkan semua pengguna dalam sebuah organisasi	`users:read`	`global.users:*` atau `global.users:id:123`
`list_all_roles`	Admin	Menampilkan semua peran Grafana	`roles:read`	`roles:*`
`get_role_details`	Admin	Mendapatkan detail untuk sebuah peran Grafana	`roles:read`	`roles:uid:editor`
`get_role_assignments`	Admin	Menampilkan penugasan untuk sebuah peran	`roles:read`	`roles:uid:editor`
`list_user_roles`	Admin	Menampilkan peran untuk pengguna	`roles:read`	`global.users:id:123`
`list_team_roles`	Admin	Menampilkan peran untuk tim	`roles:read`	`teams:id:7`
`get_resource_permissions`	Admin	Menampilkan izin untuk sebuah sumber daya	`permissions:read`	`dashboards:uid:abcd1234`
`get_resource_description`	Admin	Mendeskripsikan tipe sumber daya Grafana	`permissions:read`	`dashboards:*`
`user_info`	Pengguna	Identitas saat ini, kemampuan, dan organisasi yang dapat diakses	Tidak ada (pengguna yang masuk)	—
`search_dashboards`	Pencarian	Mencari dasbor berdasarkan kueri, UID folder, tag, atau yang dibintangi	`dashboards:read`	`dashboards:*` atau `dashboards:uid:abc123`
`get_dashboard_by_uid`	Dasbor	Mendapatkan dasbor berdasarkan uid, opsional versi yang disimpan	`dashboards:read`	`dashboards:uid:abc123`
`list_dashboard_versions`	Dasbor	Menampilkan versi tersimpan dari sebuah dasbor (versi, penulis, waktu, pesan)	`dashboards:read`	`dashboards:uid:abc123`
`update_dashboard`	Dasbor	Memperbarui atau membuat dasbor baru	`dashboards:create`, `dashboards:write`	`dashboards:`, `folders:` atau `folders:uid:xyz789`
`get_dashboard_panel_queries`	Dasbor	Mendapatkan judul panel, kueri, UID sumber data, dan tipe dari sebuah dasbor	`dashboards:read`	`dashboards:uid:abc123`
`run_panel_query`	RunPanelQuery*	Menjalankan satu atau lebih kueri panel dasbor	`dashboards:read`, `datasources:query`	`dashboards:uid:`, `datasources:uid:`
`get_dashboard_property`	Dasbor	Mengekstrak bagian tertentu dari sebuah dasbor menggunakan ekspresi JSONPath	`dashboards:read`	`dashboards:uid:abc123`
`get_dashboard_summary`	Dasbor	Mendapatkan ringkasan ringkas dari sebuah dasbor tanpa JSON lengkap	`dashboards:read`	`dashboards:uid:abc123`
`list_datasources`	Sumber Data	Menampilkan sumber data	`datasources:read`	`datasources:*`
`get_datasource`	Sumber Data	Mendapatkan sumber data berdasarkan UID atau nama	`datasources:read`	`datasources:uid:prometheus-uid`
`get_query_examples`	Contoh*	Mendapatkan contoh kueri untuk tipe sumber data	`datasources:read`	`datasources:*`
`query_prometheus`	Prometheus	Menjalankan kueri terhadap sumber data Prometheus	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_metric_metadata`	Prometheus	Menampilkan metadata metrik	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_metric_names`	Prometheus	Menampilkan nama metrik yang tersedia	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_label_names`	Prometheus	Menampilkan nama label yang cocok dengan pemilih	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_label_values`	Prometheus	Menampilkan nilai untuk label tertentu	`datasources:query`	`datasources:uid:prometheus-uid`
`query_prometheus_histogram`	Prometheus	Menghitung nilai persentil histogram	`datasources:query`	`datasources:uid:prometheus-uid`
`list_incidents`	Insiden	Menampilkan insiden di Grafana Incident, opsional dengan nilai bidang kustomnya	Peran Viewer	N/A
`create_incident`	Insiden	Membuat insiden di Grafana Incident, opsional mengatur bidang kustom	Peran Editor	N/A
`add_activity_to_incident`	Insiden	Menambahkan item aktivitas ke insiden di Grafana Incident	Peran Editor	N/A
`update_incident`	Insiden	Memperbarui insiden di Grafana Incident (status, tingkat keparahan, judul, atau bidang kustom)	Peran Editor	N/A
`get_incident`	Insiden	Mendapatkan satu insiden berdasarkan ID, termasuk bidang kustomnya	Peran Viewer	N/A
`list_incident_custom_fields`	Insiden	Menampilkan bidang kustom yang dikonfigurasi untuk insiden, dengan tipe dan opsi pilihannya	Peran Viewer	N/A
`query_loki_logs`	Loki	Mengueri dan mengambil log menggunakan LogQL (baik kueri log atau metrik)	`datasources:query`	`datasources:uid:loki-uid`
`list_loki_label_names`	Loki	Menampilkan semua nama label yang tersedia dalam log	`datasources:query`	`datasources:uid:loki-uid`
`list_loki_label_values`	Loki	Menampilkan nilai untuk label log tertentu	`datasources:query`	`datasources:uid:loki-uid`
`query_loki_stats`	Loki	Mendapatkan statistik tentang aliran log	`datasources:query`	`datasources:uid:loki-uid`
`query_loki_patterns`	Loki	Mengueri pola log yang terdeteksi untuk mengidentifikasi struktur umum	`datasources:query`	`datasources:uid:loki-uid`
`analyze_loki_labels`	Loki	Mengaudit strategi label Loki (langsung atau statis) dan opsional mendiagnosis kinerja kueri	`datasources:query`	`datasources:uid:loki-uid`
`suggest_loki_alloy_label_config`	Konfigurasi	Menghasilkan cuplikan Alloy `loki.process` yang memberlakukan label yang disetujui	N/A	N/A
`query_influxdb`	InfluxDB	Kueri InfluxDB menggunakan InfluxQL (v1) atau Flux (v2)	`datasources:query`	`datasources:uid:influxdb-uid`
`list_sql_databases`	SQL*	Daftar database, skema, atau katalog dari sumber data SQL	`datasources:query`	`datasources:uid:*`
`list_sql_tables`	SQL*	Daftar tabel dalam sumber data SQL	`datasources:query`	`datasources:uid:*`
`describe_sql_table`	SQL*	Dapatkan skema kolom untuk sebuah tabel	`datasources:query`	`datasources:uid:*`
`query_sql`	SQL*	Jalankan kueri SQL dengan substitusi makro	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_namespaces`	CloudWatch*	Daftar namespace AWS CloudWatch yang tersedia	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_metrics`	CloudWatch*	Daftar metrik dalam sebuah namespace	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_dimensions`	CloudWatch*	Daftar dimensi untuk sebuah metrik	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_dimension_values`	CloudWatch*	Daftar nilai untuk sebuah kunci dimensi	`datasources:query`	`datasources:uid:*`
`query_cloudwatch`	CloudWatch*	Jalankan kueri metrik CloudWatch	`datasources:query`	`datasources:uid:*`
`list_cloud_logging_projects`	Cloud Logging*	Daftar proyek GCP yang dapat dibaca oleh sumber data Google Cloud Logging	`datasources:query`	`datasources:uid:*`
`list_cloud_logging_buckets`	Cloud Logging*	Daftar bucket log dalam sebuah proyek GCP	`datasources:query`	`datasources:uid:*`
`list_cloud_logging_views`	Cloud Logging*	Daftar tampilan log dalam sebuah bucket log	`datasources:query`	`datasources:uid:*`
`query_cloud_logging`	Cloud Logging*	Kueri log dengan bahasa kueri Cloud Logging	`datasources:query`	`datasources:uid:*`
`query_elasticsearch`	Elasticsearch/OpenSearch*	Kueri Elasticsearch atau OpenSearch menggunakan sintaks Lucene atau Query DSL	`datasources:query`	`datasources:uid:datasource-uid`
`query_quickwit`	Quickwit*	Kueri Quickwit menggunakan sintaks Lucene atau Query DSL	`datasources:query`	`datasources:uid:quickwit-uid`
`alerting_manage_rules`	Alerting	Kelola aturan alert (daftar, dapatkan, versi, buat, perbarui, hapus)	`alert.rules:read` + `alert.rules:write` untuk mutasi	`folders:*` atau `folders:uid:alerts-folder`
`alerting_manage_routing`	Alerting	Kelola kebijakan notifikasi, titik kontak, dan interval waktu	`alert.notifications:read`	Cakupan global
`alerting_manage_silences`	Alerting	Kelola silence alerting (daftar, dapatkan, buat, perbarui, kedaluwarsa)	`alert.instances:read` + `alert.instances:write` untuk mutasi	Cakupan global
`list_oncall_schedules`	OnCall	Daftar jadwal dari Grafana OnCall	`grafana-oncall-app.schedules:read`	Cakupan khusus plugin
`get_oncall_shift`	OnCall	Dapatkan detail untuk shift OnCall tertentu	`grafana-oncall-app.schedules:read`	Cakupan khusus plugin
`get_current_oncall_users`	OnCall	Dapatkan pengguna yang sedang on-call untuk jadwal tertentu	`grafana-oncall-app.schedules:read`	Cakupan khusus plugin
`list_oncall_teams`	OnCall	Daftar tim dari Grafana OnCall	`grafana-oncall-app.user-settings:read`	Cakupan khusus plugin
`list_oncall_users`	OnCall	Daftar pengguna dari Grafana OnCall	`grafana-oncall-app.user-settings:read`	Cakupan khusus plugin
`list_alert_groups`	OnCall	Daftar grup alert dari Grafana OnCall dengan opsi pemfilteran	`grafana-oncall-app.alert-groups:read`	Cakupan khusus plugin
`get_alert_group`	OnCall	Dapatkan grup alert tertentu dari Grafana OnCall berdasarkan ID-nya	`grafana-oncall-app.alert-groups:read`	Cakupan khusus plugin
`update_alert_group`	OnCall	Akui, batalkan pengakuan, selesaikan, atau batalkan penyelesaian sebuah grup alert	`grafana-oncall-app.alert-groups:write` (dan `:read`)	Cakupan khusus plugin
`get_sift_investigation`	Sift	Ambil investigasi Sift yang ada berdasarkan UUID-nya Peran Viewer	N/A
`get_sift_analysis`	Sift	Ambil analisis tertentu dari investigasi Sift Peran Viewer	N/A
`list_sift_investigations`	Sift	Ambil daftar investigasi Sift dengan batas opsional Peran Viewer	N/A
`find_error_pattern_logs`	Sift	Menemukan pola kesalahan yang meningkat dalam log Loki. Peran Editor	N/A
`find_slow_requests`	Sift	Menemukan permintaan lambat dari sumber data tempo yang relevan. Peran Editor	N/A
`list_pyroscope_label_names`	Pyroscope	Daftar nama label yang cocok dengan pemilih	`datasources:query`	`datasources:uid:pyroscope-uid`
`list_pyroscope_label_values`	Pyroscope	Daftar nilai label yang cocok dengan pemilih untuk sebuah nama label	`datasources:query`	`datasources:uid:pyroscope-uid`
`list_pyroscope_profile_types`	Pyroscope	Daftar jenis profil yang tersedia	`datasources:query`	`datasources:uid:pyroscope-uid`
`query_pyroscope`	Pyroscope	Kueri profil, metrik, atau keduanya dari Pyroscope	`datasources:query`	`datasources:uid:pyroscope-uid`
`get_assertions`	Asserts	Dapatkan ringkasan asersi untuk entitas tertentu Izin khusus plugin	Cakupan khusus plugin
`agento11y_manage_conversations`	Agent Observability*	Daftar, cari, dan ambil percakapan LLM dari Grafana Agent Observability	`grafana-agento11y-app.conversations:read`	N/A
`agento11y_manage_generations`	Agent Observability*	Ambil detail generasi LLM dan skor evaluasi dari Grafana Agent Observability	`grafana-agento11y-app.data:read`	N/A
`agento11y_manage_agents`	Agent Observability*	Baca katalog agen: daftar agen, dapatkan satu versi agen secara lengkap, daftar riwayat versi, dan agregat skor per versi	`grafana-agento11y-app.data:read`	N/A
`agento11y_manage_evaluators`	Agent Observability*	Kelola evaluator, templat evaluator, dan katalog juri (daftar, dapatkan, upsert, fork, uji, hapus)	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` untuk mutasi dan pengujian	N/A
`agento11y_manage_eval_rules`	Agent Observability*	Kelola aturan eval dan guard (daftar, dapatkan, buat, perbarui, pratinjau, hapus)	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` untuk mutasi dan pratinjau	N/A
`agento11y_manage_eval_collections`	Agent Observability*	Kelola percakapan tersimpan dan koleksi yang mengelompokkannya (daftar, dapatkan, simpan, buat, perbarui, hapus, tambah dan hapus anggota)	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` untuk mutasi	N/A
`agento11y_manage_experiments`	Observabilitas Agen*	Membaca eksperimen offline, percobaan, skor, metadata artefak, dan faset filter; memperbarui dan membatalkan eksperimen	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` untuk mutasi	N/A
`agento11y_manage_test_suites`	Observabilitas Agen*	Mengelola rangkaian pengujian yang digunakan eksperimen offline, versinya, dan kasus ujinya (daftar, dapatkan, buat, perbarui, draf, publikasikan, upsert, hapus)	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` untuk mutasi	N/A
`ask_assistant`	Asisten*	Mengirim prompt ke Asisten Grafana dan mengembalikan balasan teks lengkap (multi-putaran melalui `contextId`)	Izin khusus plugin	Lingkup khusus plugin
`generate_deeplink`	Navigasi	Menghasilkan URL tautan dalam yang akurat untuk sumber daya Grafana	Tidak ada (pembuatan URL hanya-baca)	N/A
`get_annotations`	Anotasi	Mengambil anotasi dengan filter	`annotations:read`	`annotations:*` atau `annotations:id:123`
`create_annotation`	Anotasi	Membuat anotasi baru (format standar atau Graphite)	`annotations:write`	`annotations:*`
`update_annotation`	Anotasi	Memperbarui bidang tertentu dari anotasi (pembaruan parsial)	`annotations:write`	`annotations:*`
`delete_annotation`	Anotasi	Menghapus anotasi berdasarkan ID	`annotations:delete`	`annotations:*`
`get_annotation_tags`	Anotasi	Mendaftar tag anotasi dengan pemfilteran opsional	`annotations:read`	`annotations:*`
`list_snapshots`	Snapshot	Mendaftar snapshot dasbor dengan filter kueri dan batas opsional	`dashboards:read`	`dashboards:*` atau `dashboards:uid:abc123`
`get_snapshot`	Snapshot	Mendapatkan metadata snapshot dan muatan dasbor berdasarkan kunci snapshot	`dashboards:read`	`dashboards:*` atau `dashboards:uid:abc123`
`create_snapshot`	Snapshot	Membuat snapshot dasbor dari muatan dasbor lengkap	`dashboards:write`	`dashboards:*` atau `dashboards:uid:abc123`
`delete_snapshot`	Snapshot	Menghapus snapshot dasbor berdasarkan kunci snapshot	`dashboards:write`	`dashboards:*` atau `dashboards:uid:abc123`
`get_panel_image`	Rendering	Merender dasbor atau panel yang tersimpan — atau pratinjau provisi dari cabang repositori — sebagai gambar PNG	`dashboards:read`	`dashboards:uid:abc123`
`list_provisioning_repositories`	Provisi	Mendaftar repositori provisi (mis. sumber git-sync) dengan URL sumber, cabang, status sinkronisasi, dan kesehatannya	`provisioning.repositories:read`	N/A
`validate_provisioning_file`	Provisi	Terapkan-uji-coba file dari repositori provisi dan laporkan kesalahan validasi penerimaan	`provisioning.repositories:read`	N/A
`search_docs`	Dokumen	Mencari dokumentasi Grafana atau mendaftar grup produk (hilangkan kueri untuk mendaftar produk)	Tidak ada (grafana.com/docs publik)	N/A
`get_doc`	Dokumen	Mengambil halaman dokumentasi; atur outline_only untuk judul, atau section untuk pengambilan terbatas	Tidak ada (grafana.com/docs publik)	N/A
* Nonaktif secara bawaan. Tambahkan kategori ke `--enabled-tools` untuk mengaktifkan.

Referensi Flag CLI

Biner mcp-grafana mendukung berbagai flag baris perintah untuk konfigurasi:

Opsi Transport:

-t, --transport: Jenis transport (stdio, sse, atau streamable-http) - bawaan: stdio
--address: Host dan port untuk server SSE/streamable-http - bawaan: localhost:8000
--base-path: Jalur dasar untuk server SSE/streamable-http. /healthz dan /metrics selalu dilayani di akar server, bukan di bawah prefiks ini — keduanya adalah endpoint internal untuk probe dan scraper, dan menjauhkannya dari prefiks aplikasi memudahkan untuk mengekspos API melalui reverse proxy tanpa juga mengeksposnya
--endpoint-path: Jalur endpoint untuk server streamable-http, ditambahkan ke --base-path - bawaan: /mcp
--server-name: Nama server yang digunakan dalam jabat tangan MCP dan OTel service.name - bawaan: mcp-grafana. Menimpa variabel env GRAFANA_MCP_SERVER_NAME
--instructions-append: Teks yang ditambahkan ke instruksi server yang dikembalikan ke klien MCP saat inisialisasi, sehingga setiap agen yang terhubung melihatnya

Keamanan Transport HTTP (khusus SSE / streamable-http):

Validasi Host/Origin diberlakukan di setiap rute pada pendengar MCP — /sse, /mcp, dan /healthz / /metrics saat mereka berbagi pendengar tersebut — sehingga browser DNS-rebinding tidak dapat menjangkau salah satunya. Transport Stdio tidak terpengaruh. --healthz-address dan --metrics-address memulai pendengar terpisah yang tidak dibungkus.

--allowed-hosts: Daftar izin nilai header Host yang dipisahkan koma. Bawaan ke varian loopback dari --address (misalnya localhost:8000,127.0.0.1:8000,[::1]:8000). Nilai yang diurai menjadi kosong (tidak disetel, ,, ,, dll.) juga kembali ke bawaan sehingga kesalahan ketik tidak dapat diam-diam menonaktifkan pemeriksaan. Permintaan dengan header Host di luar daftar izin ditolak dengan 403. Berikan * untuk menonaktifkan validasi Host — hanya aman ketika reverse proxy tepercaya memvalidasi Host. Probe K8s httpGet dan scrape eksternal /metrics akan memerlukan nama host eksplisit dalam daftar ini, *, probe tcpSocket, atau port terpisah (--healthz-address / --metrics-address).
--allowed-origins: Daftar izin nilai header Origin yang dipisahkan koma. Kosong secara bawaan — permintaan apa pun yang membawa header Origin ditolak (browser selalu mengirim satu untuk permintaan lintas-origin, dan tidak ada browser yang boleh memanggil server ini secara langsung). Setel ke daftar eksplisit untuk mengizinkan klien berbasis browser, atau * untuk menonaktifkan pemeriksaan.
--allow-grafana-url-override: Aktifkan pemilihan X-Grafana-URL. Kembali ke GRAFANA_ALLOW_URL_OVERRIDE; nonaktif secara bawaan. Tanpa daftar izin, pemanggil dapat memilih URL HTTP(S) apa pun yang dapat dijangkau server.
--allowed-grafana-urls: Daftar izin URL dasar Grafana yang tepat dan dipisahkan koma untuk penimpaan URL. Kembali ke GRAFANA_ALLOWED_URLS. Memerlukan --allow-grafana-url-override; flag kosong eksplisit menonaktifkan daftar yang diwarisi.

Autentikasi Pemanggil (khusus SSE / streamable-http):

Secara opsional mengharuskan klien MCP untuk mengautentikasi ke server. Ini terpisah dari kredensial yang digunakan server untuk menjangkau Grafana. Stdio tidak terpengaruh.

--server-auth-token: Token pembawa yang harus dikirim pemanggil sebagai Authorization: Bearer <token>. Kembali ke variabel lingkungan MCP_GRAFANA_SERVER_TOKEN. Saat disetel, permintaan tanpa token valid ditolak dengan 401 sebelum alat apa pun dijalankan. Lebih suka variabel env sehingga rahasia tidak terlihat dalam argumen proses.

Autentikasi pemanggil hanya diberlakukan saat --server-auth-token disetel. Saat tidak disetel dan server mengikat alamat non-loopback, server mulai tetapi mencatat kesalahan keamanan — dipancarkan pada tingkat log error sehingga tidak disembunyikan oleh --log-level (loopback dan stdio tidak terpengaruh); rilis utama di masa depan akan menjadikannya kesalahan startup. Gunakan TLS (atau terminasi TLS) setiap kali autentikasi pemanggil diaktifkan pada alamat non-loopback. Saat autentikasi pemanggil diaktifkan, header Authorization yang divalidasi dihapus sebelum permintaan mencapai Grafana; menggabungkan --server-auth-token dengan GRAFANA_FORWARD_HEADERS=Authorization ditolak saat startup.

Penimpaan URL Grafana (khusus SSE / streamable-http):

[!WARNING] Penimpaan URL memungkinkan pemanggil MCP memilih tujuan HTTP(S) keluar. Daftar izin membatasi URL tetapi tidak mengautentikasi pemanggil atau mengikat token ke target.

Terapkan di belakang proxy pengautentikasi yang mengotorisasi setiap target, mengganti header URL dan token yang disuplai klien, dan menyuplai token yang cocok. Batasi akses jaringan keluar server ke tujuan yang disetujui.

Tanpa daftar izin, token permintaan palsu dapat menyebabkan permintaan ke layanan HTTP(S) apa pun yang dapat dijangkau, termasuk layanan internal dan metadata.

Setel GRAFANA_ALLOW_URL_OVERRIDE=true (atau --allow-grafana-url-override) untuk mengaktifkan pemilihan untuk armada besar. Untuk membatasi tujuan, juga setel GRAFANA_ALLOWED_URLS=https://one.example.com,https://two.example.com/grafana (atau --allowed-grafana-urls).

Kirim header ini pada setiap permintaan MCP yang memilih target:

X-Grafana-URL: https://one.example.com
X-Grafana-Service-Account-Token: <token for one.example.com>

Jika --server-auth-token dikonfigurasi, juga kirim Authorization: Bearer <MCP caller token>. Ini mengautentikasi ke server MCP dan terpisah dari X-Grafana-Service-Account-Token, yang untuk instance Grafana yang dipilih. Proxy Anda dapat mengirim token Grafana yang berbeda untuk setiap instance; server tidak pernah berbagi satu token yang dikonfigurasi di antara mereka. Header X-Grafana-API-Key yang tidak digunakan lagi juga berfungsi. Header URL tanpa token Grafana permintaan ditolak. Gunakan TLS untuk permintaan masuk karena mereka membawa token.

Daftar izin mencocokkan URL dasar yang tepat, termasuk skema, port, dan jalur; wildcard tidak didukung. Autentikasi Grafana bukan pertahanan SSRF.

Untuk URL yang dipilih, server tidak menggunakan GRAFANA_SERVICE_ACCOUNT_TOKEN, GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE, GRAFANA_API_KEY, autentikasi dasar lingkungan, GRAFANA_EXTRA_HEADERS, atau sertifikat klien. Verifikasi TLS tetap diaktifkan bahkan jika --tls-skip-verify disetel; file CA yang dikonfigurasi tetap berlaku. Header yang diteruskan secara eksplisit dari permintaan itu tetap berlaku. Pengalihan dan permintaan API Grafana lainnya di luar URL dasar yang dipilih diblokir. Permintaan tanpa X-Grafana-URL mempertahankan perilaku kredensial GRAFANA_URL dan lingkungan yang biasa. Opsi ini berlaku untuk SSE dan HTTP streamable saja. Untuk SSE, sertakan kedua header pemilihan pada setiap POST pesan; header pada GET SSE awal tidak terbawa ke panggilan alat.

Debug dan Pencatatan:

--debug: Aktifkan mode debug untuk pencatatan permintaan/respons HTTP terperinci
--log-level: Tingkat log (debug, info, warn, error) - bawaan: info

Opsi Klien Grafana:

--grafana-timeout: Batas waktu untuk permintaan yang dibuat oleh klien Grafana. Menerima string durasi Go (misalnya, 10s, 500ms) - bawaan: 10s
--include-args-in-spans: Sertakan argumen panggilan alat dalam span OpenTelemetry. Hanya aktifkan di lingkungan non-produksi atau saat argumen diketahui tidak mengandung PII - bawaan: false

Observabilitas:

--metrics: Aktifkan endpoint metrik Prometheus di /metrics
--metrics-address: Alamat terpisah untuk server metrik (misalnya, :9090). Jika kosong, metrik dilayani di server utama
--healthz-address: Alamat terpisah untuk /healthz (misalnya, :8080). Jika kosong, /healthz dilayani di server utama. Berbagi pendengar dengan --metrics-address saat kedua alamat cocok. Pendengar samping melewati validasi Host/Origin.
--slow-request-threshold: Catat peristiwa saat permintaan MCP apa pun (invokasi alat, daftar, pembacaan sumber daya, dll.) memakan waktu lebih lama dari durasi ini. Menerima string durasi Go (misalnya, 500ms, 5s). Bawaan 0 menonaktifkan pencatatan permintaan lambat. Lihat bagian Pencatatan permintaan lambat.
--slow-request-log-level: Tingkat log untuk peristiwa permintaan lambat (info atau warn) - bawaan: warn.

Statistik Penggunaan Anonim:

--usage-stats: Pelaporan statistik penggunaan anonim: enabled, disabled, atau log (cetak laporan yang akan dikirim ke stderr dan kirim apa pun). Menimpa variabel env GRAFANA_USAGE_STATS, yang pada gilirannya menimpa DO_NOT_TRACK; nilai apa pun yang tidak dikenali menonaktifkan pelaporan. Lihat bagian Statistik penggunaan anonim.

Manajemen Sesi:

--session-idle-timeout-minutes: Batas waktu idle sesi dalam menit. Sesi tanpa aktivitas selama durasi ini secara otomatis dibersihkan - bawaan: 30. Setel ke 0 untuk menonaktifkan pembersihan sesi. Hanya relevan untuk transport SSE dan streamable-http. Konfigurasi Alat:
--enabled-tools: Daftar kategori yang diaktifkan, dipisahkan koma - default: semua kategori kecuali admin, agento11y, assistant, athena, clickhouse, cloudlogging, cloudwatch, elasticsearch, examples, graphite, quickwit, runpanelquery, dan snowflake. Untuk mengaktifkan kategori yang dinonaktifkan, tambahkan ke daftar (misalnya, "search,datasource,...,snowflake")
--max-loki-log-limit: Jumlah maksimum baris log yang dikembalikan per panggilan query_loki_logs - default: 100. Catatan: Tetapkan ini setidaknya 1 di bawah max_entries_limit_per_query sisi server Loki untuk memungkinkan deteksi pemotongan (alat meminta limit+1 secara internal untuk mendeteksi apakah ada lebih banyak data).
--loki-guardrail-mode: Pengaman biaya kueri Loki untuk query_loki_logs - default: off. Loki tidak memberlakukan max_query_bytes_read pada kueri log tanpa filter baris, sehingga pemilih yang luas pada rentang yang luas dapat memindai terabyte; pengaman memerlukan pemilih aliran yang selektif, membatasi rentang waktu efektif (termasuk durasi rentang-vektor seperti [30d]), dan memeriksa sebelumnya estimasi byte indeks/statistik Loki sebelum menjalankan kueri. shadow mencatat kueri yang akan diblokir tetapi membiarkannya berjalan (masih membayar perjalanan pulang-pergi indeks/statistik); enforce menolaknya dengan panduan penulisan ulang yang dapat ditindaklanjuti oleh LLM. Di VictoriaLogs, pengaman hanya berlaku untuk kueri berbentuk pemilih ({...}) — ketika tidak ada pemilih yang diurai (bentuk LogsQL tanpa kurung kurawal yang normal), kueri melewati sepenuhnya, dan pemeriksaan anggaran byte tidak pernah berlaku (tidak ada estimasi indeks murah). Fallback env: GRAFANA_LOKI_GUARDRAIL_MODE.
--loki-guardrail-max-bytes: Byte maksimum yang dapat dipindai oleh satu panggilan query_loki_logs, diperkirakan melalui API indeks/statistik Loki - default: 107374182400 (100 GiB). 0 menonaktifkan pemeriksaan anggaran byte. Fallback env: GRAFANA_LOKI_GUARDRAIL_MAX_BYTES.
--loki-guardrail-max-range: Rentang waktu efektif maksimum untuk satu panggilan query_loki_logs, termasuk durasi rentang-vektor - default: 24h. Menerima string durasi Go. 0 menonaktifkan pemeriksaan rentang. Fallback env: GRAFANA_LOKI_GUARDRAIL_MAX_RANGE.
--loki-enforced-matchers: Pencocok label LogQL yang di-AND-kan ke setiap kueri Loki asli untuk membatasi aliran log mana yang dapat dibaca (misalnya environment=~"prod|staging"). Memerlukan --disable-api. Lihat Penegakan kueri Loki.
--loki-label-enumeration-fallback: Apa yang dilakukan alat enumerasi label ketika pencocok paksa negatif tidak dapat membatasi mereka: reject (default) atau unfiltered. Lihat Penegakan kueri Loki.
--disable-search: Nonaktifkan alat pencarian
--disable-datasource: Nonaktifkan alat sumber data
--disable-incident: Nonaktifkan alat insiden
--disable-prometheus: Nonaktifkan alat prometheus
--disable-write: Nonaktifkan alat tulis (operasi buat/perbarui)
--disable-query: Nonaktifkan alat kueri (alat yang menjalankan kueri terhadap sumber data); alat metadata dan penemuan tetap tersedia
--enable-query: Pertahankan alat kueri SQL mentah (query_sql, query_influxdb) terdaftar bahkan di bawah --disable-write. Setara dengan --enable-write-tools=query_sql,query_influxdb; dipertahankan sebagai singkatan untuk kasus umum itu.
--enable-write-tools: Daftar nama alat individual yang dipisahkan koma untuk tetap terdaftar bahkan di bawah --disable-write, untuk alat yang perilaku tulisnya cukup terbatas untuk memilih kembali secara independen (misalnya find_error_pattern_logs,find_slow_requests). Tidak berpengaruh pada alat yang seluruh kategorinya dinonaktifkan, misalnya melalui --disable-sift.
--disable-loki: Nonaktifkan alat loki
--disable-elasticsearch: Nonaktifkan alat elasticsearch dan opensearch
--disable-quickwit: Nonaktifkan alat quickwit
--disable-influxdb: Nonaktifkan alat InfluxDB
--disable-alerting: Nonaktifkan alat alerting
--disable-dashboard: Nonaktifkan alat dashboard
--disable-oncall: Nonaktifkan alat oncall
--disable-asserts: Nonaktifkan alat asserts
--disable-sift: Nonaktifkan alat sift
--disable-admin: Nonaktifkan alat admin
--disable-pyroscope: Nonaktifkan alat pyroscope
--disable-navigation: Nonaktifkan alat navigasi
--disable-rendering: Nonaktifkan alat rendering (ekspor gambar panel/dashboard)
--disable-snapshot: Nonaktifkan alat snapshot
--disable-cloudwatch: Nonaktifkan alat CloudWatch
--disable-cloudlogging: Nonaktifkan alat Google Cloud Logging
--disable-examples: Nonaktifkan alat contoh kueri
--disable-sql: Nonaktifkan alat sumber data SQL (ClickHouse, Snowflake, Athena, MySQL, PostgreSQL, MSSQL). Alias --disable-clickhouse, --disable-snowflake, --disable-athena juga berfungsi.
--disable-runpanelquery: Nonaktifkan alat kueri panel jalankan
--disable-graphite: Nonaktifkan alat Graphite
--disable-provisioning: Nonaktifkan alat provisioning
--disable-agento11y: Nonaktifkan alat Agent Observability
--disable-assistant: Nonaktifkan alat Grafana Assistant
--disable-docs: Nonaktifkan alat dokumentasi

Mode Hanya-Baca

Bendera --disable-write menyediakan cara untuk menjalankan server MCP dalam mode hanya-baca, mencegah operasi tulis apa pun ke instance Grafana Anda. Ini berguna untuk skenario di mana Anda ingin menyediakan akses hanya-baca yang aman seperti:

Menggunakan akun layanan dengan izin hanya-baca terbatas
Menyediakan asisten AI dengan data observabilitas tanpa kemampuan modifikasi
Menjalankan di lingkungan produksi di mana akses tulis harus dibatasi
Skenario pengujian dan pengembangan di mana Anda ingin mencegah modifikasi yang tidak disengaja

Ketika --disable-write diaktifkan, operasi tulis berikut dinonaktifkan:

Alat Dashboard:

update_dashboard

Alat Folder:

create_folder

Alat Insiden:

create_incident
add_activity_to_incident
update_incident

Alat Alerting:

alerting_manage_rules (operasi buat, perbarui, hapus)
alerting_manage_silences (operasi buat, perbarui, hapus)

Alat OnCall:

update_alert_group

Alat Anotasi:

create_annotation
update_annotation
delete_annotation

Alat Sift:

find_error_pattern_logs (membuat investigasi)
find_slow_requests (membuat investigasi)

Ini hanya membuat catatan investigasi Sift sementara melalui API Sift — mereka tidak pernah menyentuh dashboard, alert, atau sumber data Grafana. Tanpa mereka, list_sift_investigations/get_sift_investigation/get_sift_analysis tidak memiliki apa pun untuk didaftar atau diambil. Berikan --enable-write-tools=find_error_pattern_logs,find_slow_requests untuk tetap mendaftarkannya di bawah --disable-write.

Alat Snapshot:

create_snapshot
delete_snapshot

Alat Kueri SQL Mentah:

Ini menjalankan kueri apa pun yang Anda berikan tanpa memeriksanya, sehingga mereka dapat menulis ketika kredensial sumber data mengizinkannya — query_sql akan menjalankan DROP TABLE, query_influxdb akan menjalankan DELETE. Mode hanya-baca karena itu menghapusnya. Berikan --enable-query untuk tetap menyimpannya ketika kredensial sumber data diketahui hanya-baca.

query_sql
query_influxdb

Alat Agent Observability:

agento11y_manage_evaluators (operasi upsert, hapus, fork, uji evaluator)
agento11y_manage_eval_rules (operasi buat, perbarui, hapus, pratinjau aturan dan penjaga)
agento11y_manage_eval_collections (simpan dan hapus percakapan tersimpan; buat, perbarui, hapus koleksi; tambah dan hapus anggota koleksi)
agento11y_manage_experiments (operasi perbarui dan batalkan eksperimen)
agento11y_manage_test_suites (buat dan perbarui suite pengujian; buat dan publikasikan versi; upsert dan hapus kasus pengujian)

Semua operasi baca tetap tersedia, memungkinkan Anda untuk meminta dashboard, menjalankan kueri PromQL/LogQL, mendaftar sumber daya, dan mengambil data. Bahasa kueri yang tidak dapat mengekspresikan tulis — PromQL, LogQL, TraceQL, DSL Elasticsearch, Graphite, CloudWatch — tetap menyimpan alat kueri mereka dalam mode hanya-baca; hanya alat SQL mentah yang tercantum di atas yang dihapus.

Mode Bebas-Kueri

Bendera --disable-query menghapus setiap alat yang menjalankan kueri terhadap sumber data, sambil meninggalkan alat metadata dan penemuan di tempatnya. Ini berguna ketika Anda ingin asisten yang dapat menjelajahi apa yang ada — sumber data, dashboard, nama metrik, label, skema tabel — tanpa menjalankan kueri yang berpotensi mahal atau mengungkapkan data, misalnya ketika akun layanan memiliki datasources:read tetapi bukan datasources:query.

Ini adalah yang terkuat dari tiga pengaturan kueri, dan menang atas --enable-query:

Bendera	Alat kueri aman (`query_prometheus`, `query_loki_logs`, `run_panel_query`, …)	Alat kueri SQL mentah (`query_sql`, `query_influxdb`)
(tidak ada)	terdaftar	terdaftar
`--disable-write`	terdaftar	tidak terdaftar
`--disable-write --enable-query`	terdaftar	terdaftar
`--disable-query`	tidak terdaftar	tidak terdaftar
`--disable-query --enable-query`	tidak terdaftar	tidak terdaftar

Ketika --disable-query diaktifkan, alat berikut tidak terdaftar:

Alat Prometheus:

query_prometheus
query_prometheus_histogram

Alat Loki:

query_loki_logs
query_loki_patterns

query_loki_stats dan analyze_loki_labels tetap terdaftar: keduanya mengirim pemilih ke sumber data, tetapi mereka membaca indeks dan mengembalikan aliran, potongan, dan jumlah byte daripada konten log.

Alat Elasticsearch/OpenSearch dan Quickwit:

query_elasticsearch
query_quickwit

Alat InfluxDB (juga dihapus oleh --disable-write, lihat di atas):

query_influxdb

Alat Sumber Data SQL (juga dihapus oleh --disable-write, lihat di atas):

query_sql

Alat Graphite:

query_graphite
query_graphite_density

Alat CloudWatch:

query_cloudwatch

Alat Google Cloud Logging:

query_cloud_logging

Alat Pyroscope:

query_pyroscope

Alat Kueri Panel Jalankan:

run_panel_query

Kategori elasticsearch, quickwit, influxdb, dan runpanelquery tidak berisi apa pun yang lain, sehingga mereka tidak mendaftarkan alat sama sekali ketika kueri dinonaktifkan. Alat saudara di setiap kategori lain — list_prometheus_metric_names, list_loki_label_values, describe_sql_table, list_cloudwatch_metrics, list_cloud_logging_projects, dan seterusnya — tetap tersedia.

Perhatikan bahwa --disable-query menggerbang alat kueri dan jalur POST-ke-grafana_api_request /api/ds/query, tetapi tidak mengawasi setiap rute ke sumber data. Dalam mode hanya-baca, grafana_api_request mengizinkan POST ke /api/ds/query hanya ketika alat kueri diaktifkan (gerbang yang sama dengan alat SQL mentah — diblokir oleh --disable-write kecuali --enable-query menimpanya). get_panel_image, yang merender panel di sisi server, tidak terpengaruh.

Konfigurasi TLS Klien (untuk koneksi Grafana):

--tls-cert-file: Jalur ke file sertifikat TLS untuk autentikasi klien
--tls-key-file: Jalur ke file kunci privat TLS untuk autentikasi klien
--tls-ca-file: Jalur ke file sertifikat CA TLS untuk verifikasi server
--tls-skip-verify: Lewati verifikasi sertifikat TLS (tidak aman)

Konfigurasi TLS Server (hanya transport streamable-http):

--server.tls-cert-file: Jalur ke file sertifikat TLS untuk HTTPS server
--server.tls-key-file: Jalur ke file kunci privat TLS untuk HTTPS server

Penggunaan

Server MCP ini bekerja dengan instance Grafana lokal dan Grafana Cloud. Untuk Grafana Cloud, gunakan URL instance Anda (misalnya, https://myinstance.grafana.net) alih-alih http://localhost:3000 dalam contoh konfigurasi di bawah ini.

Jika menggunakan autentikasi token akun layanan, buat akun layanan di Grafana dengan izin yang cukup untuk menggunakan alat yang ingin Anda gunakan, buat token akun layanan, dan salin ke clipboard untuk digunakan dalam file konfigurasi. Ikuti dokumentasi akun layanan Grafana untuk detail tentang membuat token akun layanan. Tip: Jika Anda tidak nyaman mengonfigurasi cakupan RBAC berbutir halus, opsi yang lebih sederhana (tetapi kurang ketat) adalah menetapkan peran bawaan Editor ke akun layanan. Ini memberikan akses baca/tulis luas yang mencakup sebagian besar operasi server MCP — gunakan ketika kenyamanan lebih penting daripada persyaratan hak istimewa paling rendah yang ketat.

Catatan: Variabel lingkungan GRAFANA_API_KEY tidak digunakan lagi dan akan dihapus di versi mendatang. Harap migrasikan untuk menggunakan GRAFANA_SERVICE_ACCOUNT_TOKEN sebagai gantinya. Nama variabel lama akan terus berfungsi untuk kompatibilitas mundur tetapi akan menampilkan peringatan depresiasi.

Membaca token akun layanan dari file

Alih-alih meneruskan token secara inline melalui GRAFANA_SERVICE_ACCOUNT_TOKEN, Anda dapat mengarahkan GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE ke jalur file yang berisi token tersebut. File dibaca ulang pada setiap permintaan, sehingga token yang dirotasi akan diambil secara otomatis tanpa perlu memulai ulang server.

Ini sangat berguna di Kubernetes, di mana Secret yang dipasang sebagai volume diperbarui di tempat ketika Secret yang mendasarinya berubah (biasanya dalam ~1 menit). Jika digabungkan dengan cache klien per-permintaan — yang dikunci pada nilai token — token yang dirotasi secara transparan menghasilkan klien baru tanpa perlu memulai ulang pod dan tanpa waktu henti:

env:
  - name: GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE
    value: /var/run/secrets/grafana/token
volumeMounts:
  - name: grafana-token
    mountPath: /var/run/secrets/grafana
    readOnly: true
volumes:
  - name: grafana-token
    secret:
      secretName: grafana-mcp-token

Spasi di sekeliling (termasuk baris baru di akhir) akan dipangkas dari isi file. Jika GRAFANA_SERVICE_ACCOUNT_TOKEN dan GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE keduanya diatur, token inline akan diutamakan.

Dukungan Multi-Organisasi

Anda dapat menentukan organisasi mana yang akan digunakan dengan salah satu cara berikut:

Variabel lingkungan: Atur GRAFANA_ORG_ID ke ID organisasi numerik
Header HTTP: Atur X-Grafana-Org-Id saat menggunakan transport SSE atau streamable HTTP (header lebih diutamakan daripada variabel lingkungan — artinya Anda juga dapat mengatur organisasi default).

Ketika ID organisasi diberikan, server MCP akan mengatur header X-Grafana-Org-Id pada semua permintaan ke Grafana, memastikan bahwa operasi dilakukan dalam konteks organisasi yang ditentukan.

Pemilihan organisasi dinamis (per-panggilan)

Opsi di atas mengunci organisasi untuk seluruh koneksi. Untuk memungkinkan satu koneksi menargetkan organisasi yang berbeda per panggilan alat, mulai server dengan flag --dynamic-multi-org. Ini nonaktif secara default.

Saat diaktifkan, setiap alat menerima argumen opsional orgId yang menggantikan organisasi koneksi untuk panggilan tersebut (menggerakkan header X-Grafana-Org-Id dan, untuk API platform aplikasi, namespace Kubernetes yang diselesaikan). Alat sumber data yang diproksi juga ditemukan di setiap organisasi yang dapat diakses oleh kredensial. Panggilan yang menghilangkan orgId menggunakan organisasi default koneksi.

Ini hanya berfungsi untuk kredensial yang dimiliki lebih dari satu organisasi (misalnya identitas pengguna atau atas nama); token akun layanan tetap terikat pada satu organisasinya. Gunakan alat user_info untuk menemukan nilai orgId mana yang valid.

Contoh dengan ID organisasi:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_USERNAME": "<your username>",
        "GRAFANA_PASSWORD": "<your password>",
        "GRAFANA_ORG_ID": "2"
      }
    }
  }
}

Header HTTP Kustom

Anda dapat menambahkan header HTTP arbitrer ke semua permintaan API Grafana menggunakan variabel lingkungan GRAFANA_EXTRA_HEADERS. Nilainya harus berupa objek JSON yang memetakan nama header ke nilai.

Contoh dengan header kustom:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your token>",
        "GRAFANA_EXTRA_HEADERS": "{\"X-Custom-Header\": \"custom-value\", \"X-Tenant-ID\": \"tenant-123\"}"
      }
    }
  }
}

Proksi SOCKS5

Anda dapat merutekan semua permintaan yang dibuat server ini ke Grafana melalui proksi SOCKS5 menggunakan variabel lingkungan GRAFANA_SOCKS5_PROXY. Proksi ini hanya berlaku untuk lalu lintas Grafana server ini: proksi ini tidak mengubah variabel global HTTP_PROXY/HTTPS_PROXY, dan saat diatur, proksi ini menggantikan pemilihan proksi untuk transport Grafana saja, tanpa memengaruhi server MCP lain atau sesi shell Anda. Saat tidak diatur, perilaku tidak berubah.

URL harus menggunakan skema socks5:// atau socks5h:// (Go memperlakukannya sama: resolusi nama host didelegasikan ke proksi) dan dapat menyertakan kredensial, misalnya socks5://user:pass@127.0.0.1:1080.

Contoh:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your token>",
        "GRAFANA_SOCKS5_PROXY": "socks5://127.0.0.1:1080"
      }
    }
  }
}

URL proksi yang tidak valid adalah kesalahan saat startup, dan jika pembuatan koneksi terproksi gagal saat runtime, server akan gagal tertutup daripada diam-diam mengirim lalu lintas Grafana secara langsung.

Meneruskan Header dari Klien (Khusus SSE/Streamable-HTTP)

Ketika server MCP berjalan di belakang gateway atau reverse proxy yang menangani SSO (misalnya AWS ALB dengan OIDC), cookie sesi setiap pengguna harus mencapai Grafana sehingga dapat mengaitkan permintaan dengan pengguna yang terautentikasi. Variabel lingkungan GRAFANA_FORWARD_HEADERS memungkinkan ini dengan menentukan daftar izin nama header yang dipisahkan koma untuk disalin dari permintaan HTTP masuk ke setiap permintaan API Grafana keluar.

Ini hanya berlaku saat menggunakan transport SSE (-t sse) atau streamable-http (-t streamable-http). Ini tidak berpengaruh dalam mode stdio.

Contoh: teruskan cookie sesi

{
  "env": {
    "GRAFANA_URL": "https://grafana.internal",
    "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your token>",
    "GRAFANA_FORWARD_HEADERS": "Cookie"
  }
}

Anda dapat meneruskan beberapa header dengan memisahkannya dengan koma:

GRAFANA_FORWARD_HEADERS=Cookie,X-Session-Id

Header yang diteruskan digabungkan dengan header apa pun yang ditentukan di GRAFANA_EXTRA_HEADERS. Jika nama header muncul di keduanya, nilai dari permintaan masuk lebih diutamakan untuk permintaan tersebut.

Header konteks jejak (traceparent, tracestate, baggage) adalah pengecualian: server menyebarkan konteks jejak itu sendiri, sehingga nilai yang diteruskan tidak akan pernah menggantikan yang disuntikkannya. Lihat observability.

Anda memiliki beberapa opsi untuk menginstal mcp-grafana:
- uvx (disarankan): Jika Anda memiliki uv terinstal, tidak diperlukan pengaturan tambahan — uvx akan secara otomatis mengunduh dan menjalankan server:
```
uvx mcp-grafana
```
- Citra Docker: Gunakan citra Docker yang sudah dibuat sebelumnya dari Docker Hub.
  
  Penting: Titik masuk citra Docker dikonfigurasi untuk menjalankan server MCP dalam mode SSE secara default, tetapi sebagian besar pengguna akan ingin menggunakan mode STDIO untuk integrasi langsung dengan asisten AI seperti Claude Desktop:
  1. Mode STDIO: Untuk mode stdio, Anda harus secara eksplisit mengganti default dengan -t stdio dan menyertakan flag -i untuk menjaga stdin tetap terbuka:
```
docker pull grafana/mcp-grafana
# For local Grafana:
docker run --rm -i -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana -t stdio
# For Grafana Cloud:
docker run --rm -i -e GRAFANA_URL=https://myinstance.grafana.net -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana -t stdio
```
  Catatan — amankan mode jaringan: Dalam mode SSE dan streamable-http, kontainer mengikat alamat non-loopback (0.0.0.0:8000). Tanpa token pemanggil, server mulai tetapi mencatat kesalahan keamanan (pada tingkat log error, sehingga tidak disembunyikan oleh --log-level; dan akan menolak untuk mulai di rilis utama mendatang). Atur MCP_GRAFANA_SERVER_TOKEN untuk mewajibkan Authorization: Bearer <token> dari klien (disarankan). Mode STDIO tidak terpengaruh. Lihat Autentikasi Pemanggil.
  1. Mode SSE: Dalam mode ini, server berjalan sebagai server HTTP yang terhubung oleh klien. Anda harus mengekspos port 8000 menggunakan flag -p:
```
docker pull grafana/mcp-grafana
docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> grafana/mcp-grafana
```
  1. Mode HTTP Streamable: Dalam mode ini, server beroperasi sebagai proses independen yang dapat menangani beberapa koneksi klien. Anda harus mengekspos port 8000 menggunakan flag -p: Untuk mode ini Anda harus secara eksplisit mengganti default dengan -t streamable-http
```
docker pull grafana/mcp-grafana
docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> grafana/mcp-grafana -t streamable-http
```
  Untuk mode HTTP streamable HTTPS dengan sertifikat TLS server:
```
docker pull grafana/mcp-grafana
docker run --rm -p 8443:8443 \
  -v /path/to/certs:/certs:ro \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> \
  -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> \
  grafana/mcp-grafana \
  -t streamable-http \
  -addr :8443 \
  --server.tls-cert-file /certs/server.crt \
  --server.tls-key-file /certs/server.key
```
- Unduh biner: Unduh rilis terbaru mcp-grafana dari halaman rilis dan letakkan di $PATH Anda.
- Bangun dari sumber: Jika Anda memiliki toolchain Go terinstal, Anda juga dapat membangun dan menginstalnya dari sumber, menggunakan variabel lingkungan GOBIN untuk menentukan direktori tempat biner harus diinstal. Ini juga harus ada di $PATH Anda.
```
GOBIN="$HOME/go/bin" go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest
```
- Terapkan ke Kubernetes menggunakan Helm: gunakan bagan Helm dari repositori helm-charts Grafana
```
helm repo add grafana https://grafana.github.io/helm-charts
helm install --set grafana.apiKey=<Grafana_ApiKey> --set grafana.url=<GrafanaUrl> my-release grafana/grafana-mcp
```

Tambahkan konfigurasi server ke file konfigurasi klien Anda. Misalnya, untuk Claude Desktop:

Jika menggunakan uvx:

{
  "mcpServers": {
    "grafana": {
      "command": "uvx",
      "args": ["mcp-grafana"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

Jika menggunakan biner:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>",
        // If using username/password authentication
        "GRAFANA_USERNAME": "<your username>",
        "GRAFANA_PASSWORD": "<your password>",
        // Optional: specify organization ID for multi-org support
        "GRAFANA_ORG_ID": "1"
      }
    }
  }
}

Catatan: jika Anda melihat Error: spawn mcp-grafana ENOENT di Claude Desktop, Anda perlu menentukan jalur lengkap ke mcp-grafana.

Jika menggunakan Docker:

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN",
        "grafana/mcp-grafana",
        "-t",
        "stdio"
      ],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>",
        // If using username/password authentication
        "GRAFANA_USERNAME": "<your username>",
        "GRAFANA_PASSWORD": "<your password>",
        // Optional: specify organization ID for multi-org support
        "GRAFANA_ORG_ID": "1"
      }
    }
  }
}

Catatan: Argumen -t stdio sangat penting di sini karena menggantikan mode SSE default di citra Docker.

Menggunakan VSCode dengan server MCP jarak jauh

Jika Anda menggunakan VSCode dan menjalankan server MCP dalam mode SSE (yang merupakan default saat menggunakan citra Docker tanpa mengganti transport), pastikan .vscode/settings.json Anda menyertakan yang berikut:

"mcp": {
  "servers": {
    "grafana": {
      "type": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}

Untuk mode HTTP streamable HTTPS dengan sertifikat TLS server:

"mcp": {
  "servers": {
    "grafana": {
      "type": "sse",
      "url": "https://localhost:8443/sse"
    }
  }
}

Mode Debug

Anda dapat mengaktifkan mode debug untuk transport Grafana dengan menambahkan flag -debug ke perintah. Ini akan memberikan pencatatan terperinci tentang permintaan dan respons HTTP antara server MCP dan API Grafana, yang dapat membantu pemecahan masalah.

Untuk menggunakan mode debug dengan konfigurasi Claude Desktop, perbarui konfigurasi Anda sebagai berikut:

Jika menggunakan biner:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": ["-debug"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

Jika menggunakan Docker:

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN",
        "grafana/mcp-grafana",
        "-t",
        "stdio",
        "-debug"
      ],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

Catatan: Seperti konfigurasi standar, argumen -t stdio diperlukan untuk menggantikan mode SSE default di citra Docker.

Konfigurasi TLS

Jika instance Grafana Anda berada di belakang mTLS atau memerlukan sertifikat TLS kustom, Anda dapat mengonfigurasi server MCP untuk menggunakan sertifikat kustom. Server mendukung opsi konfigurasi TLS berikut:

--tls-cert-file: Jalur ke file sertifikat TLS untuk autentikasi klien
--tls-key-file: Jalur ke file kunci privat TLS untuk autentikasi klien
--tls-ca-file: Jalur ke file sertifikat CA TLS untuk verifikasi server
--tls-skip-verify: Lewati verifikasi sertifikat TLS (tidak aman, gunakan hanya untuk pengujian)

Contoh dengan autentikasi sertifikat klien:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [
        "--tls-cert-file",
        "/path/to/client.crt",
        "--tls-key-file",
        "/path/to/client.key",
        "--tls-ca-file",
        "/path/to/ca.crt"
      ],
      "env": {
        "GRAFANA_URL": "https://secure-grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

Contoh dengan Docker:

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/path/to/certs:/certs:ro",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN",
        "grafana/mcp-grafana",
        "-t",
        "stdio",
        "--tls-cert-file",
        "/certs/client.crt",
        "--tls-key-file",
        "/certs/client.key",
        "--tls-ca-file",
        "/certs/ca.crt"
      ],
      "env": {
        "GRAFANA_URL": "https://secure-grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

Konfigurasi TLS diterapkan ke semua klien HTTP yang digunakan oleh server MCP, termasuk:

Klien OpenAPI Grafana utama
Klien sumber data Prometheus
Klien sumber data Loki
Klien manajemen insiden
Klien investigasi Sift
Klien alerting
Klien Asserts

Contoh Penggunaan CLI Langsung:

Untuk pengujian dengan sertifikat yang ditandatangani sendiri:

./mcp-grafana --tls-skip-verify -debug

Dengan autentikasi sertifikat klien:

./mcp-grafana \
  --tls-cert-file /path/to/client.crt \
  --tls-key-file /path/to/client.key \
  --tls-ca-file /path/to/ca.crt \
  -debug

Dengan sertifikat CA kustom saja:

./mcp-grafana --tls-ca-file /path/to/ca.crt

Penggunaan Terprogram:

Jika Anda menggunakan pustaka ini secara terprogram, Anda juga dapat membuat fungsi konteks yang mendukung TLS:

// Using struct literals
tlsConfig := &mcpgrafana.TLSConfig{
    CertFile: "/path/to/client.crt",
    KeyFile:  "/path/to/client.key",
    CAFile:   "/path/to/ca.crt",
}
grafanaConfig := mcpgrafana.GrafanaConfig{
    Debug:     true,
    TLSConfig: tlsConfig,
}
contextFunc := mcpgrafana.ComposedStdioContextFunc(grafanaConfig)

// Or inline
grafanaConfig := mcpgrafana.GrafanaConfig{
    Debug: true,
    TLSConfig: &mcpgrafana.TLSConfig{
        CertFile: "/path/to/client.crt",
        KeyFile:  "/path/to/client.key",
        CAFile:   "/path/to/ca.crt",
    },
}
contextFunc := mcpgrafana.ComposedStdioContextFunc(grafanaConfig)

Validasi URL:

Saat memanggil NewGrafanaClient secara langsung (stdio atau konstruksi terprogram), validasi URL terlebih dahulu untuk menghindari panic yang dapat dijangkau:

if err := mcpgrafana.ValidateGrafanaURL(urlFromHeader); err != nil {
    http.Error(w, err.Error(), http.StatusBadRequest)
    return
}
client := mcpgrafana.NewGrafanaClient(ctx, urlFromHeader, apiKey, nil)

Konfigurasi TLS Server (Khusus Transport HTTP Streamable)

Saat menggunakan transport HTTP streamable (-t streamable-http), Anda dapat mengonfigurasi server MCP untuk menyajikan HTTPS alih-alih HTTP. Ini berguna ketika Anda perlu mengamankan koneksi antara klien MCP Anda dan server itu sendiri.

Server mendukung opsi konfigurasi TLS berikut untuk transport HTTP streamable:

--server.tls-cert-file: Jalur ke file sertifikat TLS untuk HTTPS server (diperlukan untuk TLS)
--server.tls-key-file: Jalur ke file kunci privat TLS untuk HTTPS server (diperlukan untuk TLS)

Catatan: Flag ini sepenuhnya terpisah dari flag TLS klien yang didokumentasikan di atas. Flag TLS klien mengonfigurasi bagaimana server MCP terhubung ke Grafana, sementara flag TLS server ini mengonfigurasi bagaimana klien terhubung ke server MCP saat menggunakan transport HTTP streamable.

Contoh dengan server HTTP streamable HTTPS:

./mcp-grafana \
  -t streamable-http \
  --server.tls-cert-file /path/to/server.crt \
  --server.tls-key-file /path/to/server.key \
  -addr :8443

Ini akan memulai server MCP pada port HTTPS 8443. Klien kemudian akan terhubung ke https://localhost:8443/ alih-alih http://localhost:8000/.

Contoh Docker dengan TLS server:

docker run --rm -p 8443:8443 \
  -v /path/to/certs:/certs:ro \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> \
  grafana/mcp-grafana \
  -t streamable-http \
  -addr :8443 \
  --server.tls-cert-file /certs/server.crt \
  --server.tls-key-file /certs/server.key

Titik Akhir Pemeriksaan Kesehatan

Saat menggunakan transport SSE (-t sse) atau streamable HTTP (-t streamable-http), server MCP mengekspos titik akhir pemeriksaan kesehatan di /healthz. Titik akhir ini dapat digunakan oleh penyeimbang beban, sistem pemantauan, atau platform orkestrasi untuk memverifikasi bahwa server berjalan dan menerima koneksi.

Titik Akhir: GET /healthz

Respons:

Kode Status: 200 OK
Isi: ok

Contoh penggunaan:

# For streamable HTTP or SSE transport on default port
curl http://localhost:8000/healthz

# Probe a side listener while MCP stays on loopback (Kubernetes + sidecar)
./mcp-grafana -t streamable-http --address 127.0.0.1:8000 --healthz-address :8080
curl http://127.0.0.1:8080/healthz

# With --base-path /my-base the MCP routes move under the prefix
# (/my-base/sse, /my-base/mcp), but healthz does not:
curl http://localhost:8000/healthz          # 200 ok
curl http://localhost:8000/my-base/healthz  # 404

Catatan: Titik akhir pemeriksaan kesehatan hanya tersedia saat menggunakan transport SSE atau streamable HTTP. Ini tidak tersedia saat menggunakan transport stdio (-t stdio), karena stdio tidak mengekspos server HTTP.

Statistik Penggunaan Anonim

Server dapat melaporkan statistik penggunaan anonim tentang dirinya sendiri ke Grafana Labs: alat mana yang dipanggil, berapa banyak panggilan yang gagal, dan bagaimana server dikonfigurasi. Satu laporan mencakup satu proses server — bukan satu pengguna atau satu percakapan — dan dikirim setiap 4 jam plus sekali saat dimatikan. Pelaporan dinonaktifkan secara default dalam rilis ini — endpoint penerima belum aktif — dan rilis berikutnya akan mengubah default menjadi aktif dengan opsi keluar yang sama.

Argumen alat, nama sumber daya, kueri, baris log, pesan kesalahan, dan kredensial tidak pernah dikirim. Bendera dicatat hanya berdasarkan nama, tidak pernah berdasarkan nilai, dan instance Grafana hanya dijelaskan sebagai cloud atau self_hosted — tidak pernah berdasarkan URL, hostname, slug tumpukan, atau org. Tidak ada yang bersifat per pengguna, per sesi, atau per klien: tidak ada pengidentifikasi sesi di jaringan dan tidak ada cara untuk menghubungkan panggilan alat ke klien tertentu.

# Turn reporting on
mcp-grafana --usage-stats=enabled

# Turn it off (or GRAFANA_USAGE_STATS=disabled)
mcp-grafana --usage-stats=disabled

# Print what would be sent, to stderr, and send nothing
GRAFANA_USAGE_STATS=log mcp-grafana

DO_NOT_TRACK=1 juga menonaktifkan pelaporan, mengikuti konvensi DO_NOT_TRACK lintas alat. Hanya 1 yang berpengaruh, hanya dapat menonaktifkan, dan baik --usage-stats maupun GRAFANA_USAGE_STATS menimpanya, sehingga host yang mengaturnya secara global masih dapat mengaktifkan kembali satu server.

GRAFANA_USAGE_STATS_ENDPOINT mengubah tujuan. Ini bukan opsi keluar.

Untuk daftar bidang lengkap, apa yang tidak pernah dikirim, cara membaca data dan keterbatasannya, lihat Statistik penggunaan anonim.

Observabilitas

Server MCP mendukung metrik Prometheus, pelacakan terdistribusi OpenTelemetry, dan ekspor log OpenTelemetry, mengikuti konvensi semantik OTel MCP. Pelacakan dan ekspor log dikonfigurasi melalui variabel lingkungan OTEL_* standar dan berfungsi dengan transport apa pun.

Catatan: mcp-grafana saat ini hanya mendukung transport OTLP/gRPC untuk pelacakan dan log. OTEL_EXPORTER_OTLP_PROTOCOL (dan varian _TRACES_PROTOCOL / _LOGS_PROTOCOL) tidak dihormati — gRPC digunakan apa pun adanya.

Metrik

Saat menggunakan transport SSE atau HTTP yang dapat dialirkan, aktifkan metrik Prometheus dengan bendera --metrics:

# Metrics served on the main server at /metrics
./mcp-grafana -t streamable-http --metrics

# Metrics served on a separate address
./mcp-grafana -t streamable-http --metrics --metrics-address :9090

Metrik yang Tersedia:

Metrik	Tipe	Deskripsi
`mcp_server_operation_duration_seconds`	Histogram	Durasi operasi MCP (label: `mcp_method_name`, `gen_ai_tool_name`, `error_type`, `network_transport`, `mcp_protocol_version`)
`mcp_server_session_duration_seconds`	Histogram	Durasi sesi klien MCP (label: `network_transport`, `mcp_protocol_version`)
`http_server_request_duration_seconds`	Histogram	Durasi permintaan server HTTP (dari otelhttp)

Catatan: Metrik hanya tersedia saat menggunakan transport SSE atau HTTP yang dapat dialirkan. Metrik tidak tersedia dengan transport stdio.

Saat pengaman biaya Loki (--loki-guardrail-mode) diaktifkan, empat penghitung lagi mencatat keputusannya:

Metrik	Tipe	Deskripsi
`mcp_loki_guardrail_admitted_total`	Penghitung	Kueri yang lolos setiap pemeriksaan yang diaktifkan (label: `backend`)
`mcp_loki_guardrail_would_block_total`	Penghitung	Kueri yang gagal dalam pemeriksaan mode `shadow` dan tetap dijalankan (label: `backend`, `reason`)
`mcp_loki_guardrail_blocked_total`	Penghitung	Kueri yang ditolak dalam mode `enforce` (label: `backend`, `reason`)
`mcp_loki_guardrail_fail_open_total`	Penghitung	Kueri yang tidak dapat dievaluasi oleh pengaman dan diterima (label: `backend`, `cause`)

reason adalah salah satu dari selector, range, bytes; cause adalah salah satu dari unparseable, estimate_failed; backend adalah salah satu dari loki, victorialogs, unknown. Kueri yang memicu beberapa pemeriksaan dihitung sekali, diberi label dengan pemeriksaan yang dijalankan pertama (selector, lalu range, lalu bytes), sehingga empat penghitung mempartisi populasi yang dijaga. Lihat Observabilitas untuk cara membacanya selama peluncuran shadow → enforce.

Penyemat perpustakaan harus menetapkan GrafanaConfig.MeterProvider (rekanan metrik dari GrafanaConfig.Logger): pengaman berjalan di dalam penangan alat, sehingga tidak memiliki opsi konstruktor, dan proses yang memasang MeterProvider global noop akan menjatuhkan setiap rekaman.

Pencatatan permintaan lambat

Bendera --slow-request-threshold mengeluarkan peristiwa log terstruktur setiap kali permintaan MCP (pemanggilan alat, daftar, pembacaan sumber daya, dll.) melebihi durasi yang diberikan. Ini berguna untuk mendiagnosis kueri dan panggilan alat yang lambat tanpa tenggelam dalam log debug penuh.

# Warn on any request slower than 500ms (works on all transports)
./mcp-grafana -t streamable-http --slow-request-threshold 500ms

# Same thing on stdio (the feature is transport-agnostic, unlike --metrics)
./mcp-grafana -t stdio --slow-request-threshold 500ms

# Log at INFO level instead of WARN (useful during investigation)
./mcp-grafana -t streamable-http --slow-request-threshold 500ms --slow-request-log-level info

Peristiwa log membawa atribut terstruktur ini:

Atribut	Deskripsi
`mcp.method`	Metode MCP (misalnya, `tools/call`, `tools/list`, `resources/read`)
`duration`	Durasi permintaan yang diamati
`threshold`	Ambang batas yang dikonfigurasi
`tool`	Nama alat (hanya ada untuk metode `tools/call`)
`error`	Nilai kesalahan, saat permintaan gagal (konteks upaya terbaik; konten dikendalikan oleh pembungkusan kesalahan upstream)
`error.type`	Klasifikasi kesalahan kardinalitas terbatas (`_OTHER` untuk kesalahan tanpa tipe)

Pencatatan permintaan lambat berfungsi di semua transport (termasuk stdio) dan tidak memerlukan --metrics. Ambang batas default 0 menonaktifkannya sepenuhnya. Alat yang diproksi mengalir melalui tools/call dan tercakup secara otomatis.

Pelacakan

Pelacakan terdistribusi dikonfigurasi melalui variabel lingkungan OTEL_* standar dan berfungsi secara independen dari bendera --metrics. Saat OTEL_EXPORTER_OTLP_ENDPOINT (atau OTEL_EXPORTER_OTLP_TRACES_ENDPOINT khusus sinyal) diatur, server mengekspor pelacakan melalui OTLP/gRPC:

# Send traces to a local Tempo instance
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \
OTEL_EXPORTER_OTLP_INSECURE=true \
./mcp-grafana -t streamable-http

# Send traces to Grafana Cloud with authentication
OTEL_EXPORTER_OTLP_ENDPOINT=https://tempo-us-central1.grafana.net:443 \
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ..." \
./mcp-grafana -t streamable-http

Rentang panggilan alat mengikuti penamaan semconv (tools/call <tool_name>) dan menyertakan atribut seperti gen_ai.tool.name, mcp.method.name, dan mcp.session.id. Server juga mendukung propagasi konteks pelacakan W3C dari bidang _meta permintaan panggilan alat.

Log

Saat OTEL_EXPORTER_OTLP_ENDPOINT (atau OTEL_EXPORTER_OTLP_LOGS_ENDPOINT khusus sinyal) diatur, server juga mengekspor log terstruktur melalui OTLP/gRPC selain output stderr teks biasa yang ada. Jembatan otelslog secara otomatis melampirkan trace_id dan span_id dari rentang aktif, sehingga catatan log berkorelasi dengan pelacakan yang sudah dipancarkan server.

Pelacakan dan log menyelesaikan endpoint mereka secara independen, sehingga kedua sinyal dapat diaktifkan secara terpisah: mengatur hanya OTEL_EXPORTER_OTLP_TRACES_ENDPOINT mengaktifkan pelacakan tanpa ekspor log, mengatur hanya OTEL_EXPORTER_OTLP_LOGS_ENDPOINT mengaktifkan ekspor log tanpa pelacakan, dan OTEL_EXPORTER_OTLP_ENDPOINT generik mengaktifkan keduanya.

Jika Anda menggunakan OTEL_EXPORTER_OTLP_ENDPOINT generik tetapi ingin menonaktifkan ekspor log (misalnya backend Anda tidak mendukung LogsService), atur:

OTEL_LOGS_EXPORTER=none

Ini mencegah server membuat eksportir log OTLP apa pun terlepas dari konfigurasi endpoint, menghindari kesalahan seperti unknown service opentelemetry.proto.collector.logs.v1.LogsService.

Pencatatan stderr tidak berubah saat pencatatan OTLP diaktifkan; Anda dapat terus mengandalkan log kontainer atau mengalirkan stderr ke /dev/null jika Anda lebih suka.

# Send both logs and traces to a local OTel collector
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \
OTEL_EXPORTER_OTLP_INSECURE=true \
./mcp-grafana -t streamable-http

Transportnya adalah OTLP/gRPC (port default 4317). Log dapat dikirim langsung ke backend terkelola mana pun yang menerima OTLP/gRPC — misalnya, Grafana Cloud — dengan menunjuk OTEL_EXPORTER_OTLP_LOGS_ENDPOINT (atau OTEL_EXPORTER_OTLP_ENDPOINT generik) ke endpoint gRPC jarak jauh dan menyediakan auth melalui OTEL_EXPORTER_OTLP_LOGS_HEADERS (atau OTEL_EXPORTER_OTLP_HEADERS), mencerminkan contoh pelacakan di atas. Kolektor OTel lokal opsional — berguna untuk fan-out, batching, atau perutean multi-backend, tetapi tidak wajib.

Varian khusus sinyal OTEL_EXPORTER_OTLP_LOGS_ENDPOINT, OTEL_EXPORTER_OTLP_LOGS_HEADERS, OTEL_EXPORTER_OTLP_LOGS_INSECURE, OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE, OTEL_EXPORTER_OTLP_LOGS_TIMEOUT, dan OTEL_EXPORTER_OTLP_LOGS_COMPRESSION dihormati dan menimpa rekanan generik OTEL_EXPORTER_OTLP_* — lihat spesifikasi eksportir OTel untuk daftar lengkap dan aturan prioritas.

Jika kolektor yang dikonfigurasi tidak dapat dijangkau, catatan log di-buffer dalam memori (antrean default: 2048) dan catatan tertua dijatuhkan setelah antrean penuh. Proses berlanjut tanpa memblokir layanan. Konfigurasikan kolektor OTel lokal jika Anda memerlukan buffering tanpa kehilangan selama pemadaman.

Log juga diekspor di bawah transport stdio, yang memudahkan untuk memusatkan log dari instance mcp-grafana lokal yang dipanggil oleh klien IDE.

Contoh Docker dengan metrik, pelacakan, dan log:

docker run --rm -p 8000:8000 \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your token> \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=http://tempo:4317 \
  -e OTEL_EXPORTER_OTLP_INSECURE=true \
  grafana/mcp-grafana \
  -t streamable-http --metrics

Penegakan kueri Loki

--loki-enforced-matchers memungkinkan operator membatasi aliran log Loki mana yang dapat dibaca server, dengan AND-ing serangkaian pencocok label LogQL tetap ke setiap kueri Loki asli yang dikeluarkan server. Ini berguna ketika sumber data berisi aliran yang tidak boleh diekspos (misalnya log yang mungkin membawa informasi sensitif) tetapi Anda tidak dapat membatasi akses di lapisan Grafana atau Loki (OSS tidak memiliki kontrol akses label per-sumber data atau per-pengguna).

# Only ever read prod/staging environments (allowlist)
./mcp-grafana --loki-enforced-matchers 'environment=~"prod|staging"' --disable-api

# Never read the vault or payments namespaces (exclusion)
./mcp-grafana --loki-enforced-matchers 'namespace!~"vault|payments"' --disable-api

Cara kerjanya:

Pencocok diurai sekali saat startup (input tidak valid menghentikan server) dan ditambahkan ke setiap pemilih aliran di setiap kueri. Karena Loki AND-s pencocok dalam pemilih, kueri pengguna hanya dapat mempersempit hasil dalam batas yang ditegakkan — tidak pernah dapat memperluasnya. Pemilih pengguna yang bertentangan dengan kebijakan (misalnya meminta {namespace="vault"} di bawah pengecualian) hanya mengembalikan tidak ada.
Ini mencakup query_loki_logs, query_loki_stats, query_loki_patterns, list_loki_label_names, dan list_loki_label_values.
Ini gagal tertutup: kueri apa pun yang tidak dapat diurai ditolak daripada dikirim tanpa filter.
Sumber data VictoriaLogs menggunakan LogsQL, yang tidak dapat ditulis ulang dengan aman, sehingga ditolak sepenuhnya saat penegakan diaktifkan.
Pencocok negatif murni tidak dapat membatasi endpoint enumerasi label (Loki menolak pemilih berdiri sendiri tanpa pencocok positif). Kontrol kasus tepi itu dengan --loki-label-enumeration-fallback (reject secara default, atau unfiltered untuk mengizinkan enumerasi metadata label tanpa cakupan — baris log tidak pernah diekspos). Pencocok positif/daftar izin tidak terpengaruh.

[!PENTING] Penegakan hanya berlaku untuk alat kueri Loki. Alat lain dapat mencapai data log Loki melalui jalur yang tidak pernah menyentuh backend yang ditegakkan, jadi agar pembatasan benar-benar berlaku, Anda juga harus menonaktifkannya:

--disable-api — grafana_api_request dapat mengkueri proksi sumber data Loki secara langsung (bypass penuh).

--disable-rendering — get_panel_image merender panel Loki di sisi server, menghasilkan gambar dengan baris log tanpa batasan.

--disable-sift — Investigasi Sift menganalisis log Loki di sisi server di semua aliran.

--disable-assistant — ask_assistant mendelegasikan ke Asisten Grafana, yang membaca Loki di sisi server di semua aliran. Hanya terdaftar saat alat tulis diaktifkan, sehingga --disable-write juga menutupnya.

Server mencatat peringatan saat startup yang menyebutkan masing-masing yang masih diaktifkan. run_panel_query aman (ini menggunakan kembali jalur kueri yang ditegakkan). Alat Tempo mengkueri pelacakan, bukan log Loki, sehingga bukan bypass. Snapshot dasbor (--disable-snapshot) juga dapat menyematkan data panel log yang ditangkap di luar penegakan.

Pemecahan Masalah

Kompatibilitas Versi Grafana

Jika Anda mengalami kesalahan berikut saat menggunakan alat terkait sumber data:

get datasource by uid : [GET /datasources/uid/{uid}][400] getDataSourceByUidBadRequest {"message":"id is invalid"}

Ini biasanya menunjukkan bahwa Anda menggunakan versi Grafana lebih awal dari 9.0. Endpoint API /datasources/uid/{uid} diperkenalkan di Grafana 9.0, dan operasi sumber data akan gagal pada versi sebelumnya.

Solusi: Tingkatkan instance Grafana Anda ke versi 9.0 atau lebih baru untuk mengatasi masalah ini.

Pengembangan

Kontribusi diterima! Silakan baca CONTRIBUTING.md terlebih dahulu — ini mencakup apa yang termasuk dalam server ini dan cara mengusulkannya. Jika Anda menambahkan alat baru, silakan buka proposal alat sebelum menulis kode. Setiap alat yang aktif secara default dikirim ke model pada setiap permintaan oleh setiap pengguna, jadi kami lebih suka mendiskusikan ide tersebut daripada menolak pull request yang sudah selesai. Perbaikan bug, dokumentasi, tes, dan parameter baru pada alat yang sudah ada tidak memerlukan proposal — cukup kirim PR.

Proyek ini ditulis dalam Go. Instal Go mengikuti petunjuk untuk platform Anda.

Untuk menjalankan server secara lokal dalam mode STDIO (yang merupakan default untuk pengembangan lokal), gunakan:

make run

Untuk menjalankan server secara lokal dalam mode SSE, gunakan:

go run ./cmd/mcp-grafana --transport sse

Anda juga dapat menjalankan server menggunakan transport SSE di dalam image Docker yang dibuat khusus. Sama seperti image Docker yang dipublikasikan, entrypoint image khusus ini default ke mode SSE. Untuk membangun image, gunakan:

make build-image

Dan untuk menjalankan image dalam mode SSE (default), gunakan:

docker run -it --rm -p 8000:8000 mcp-grafana:latest

Jika Anda perlu menjalankannya dalam mode STDIO sebagai gantinya, timpa pengaturan transport:

docker run -it --rm mcp-grafana:latest -t stdio

Pengujian

Ada tiga jenis tes yang tersedia:

Tes Unit (tidak memerlukan dependensi eksternal):

make test-unit

Anda juga dapat menjalankan tes unit dengan:

make test

Tes Integrasi (memerlukan kontainer docker yang berjalan):

make test-integration

Tes Cloud (memerlukan instance Grafana cloud dan kredensial):

make test-cloud

Catatan: Tes cloud dikonfigurasi secara otomatis di CI. Untuk pengembangan lokal, Anda perlu menyiapkan instance Grafana Cloud dan kredensial Anda sendiri.

Tes integrasi yang lebih komprehensif akan memerlukan instance Grafana yang berjalan secara lokal di port 3000; Anda dapat memulainya dengan Docker Compose:

docker-compose up -d

Tes integrasi dapat dijalankan dengan:

make test-all

Jika Anda menambahkan lebih banyak alat, silakan tambahkan tes integrasi untuk alat tersebut. Tes yang ada seharusnya menjadi titik awal yang baik.

Linting

Untuk lint kode, jalankan:

make lint

Ini mencakup linter khusus yang memeriksa koma yang tidak di-escape dalam tag struct jsonschema. Koma di bidang description harus di-escape dengan \\, untuk mencegah pemotongan diam-diam. Anda dapat menjalankan hanya linter ini dengan:

make lint-jsonschema

Lihat dokumentasi Linter JSONSchema untuk detail lebih lanjut.

Lisensi

Proyek ini dilisensikan di bawah Lisensi Apache, Versi 2.0.