Grafana MCP Server: Scope OAuth untuk Claude Code dan Cursor

Pertanyaan yang membuat saya membaca dokumentasi Grafana Cloud MCP baris demi baris sebenarnya kecil: kalau saya arahkan Claude Code ke telemetri production, apa hal terburuk yang bisa dilakukannya dengan token yang akhirnya dipegang? Halaman consent menawarkan tiga level akses, dan cara baca yang paling jelas ternyata sedikit keliru.

Tulisan ini adalah pembacaan dekat atas dokumentasi resmi Grafana untuk server hosted, panduan registrasi OAuth client, dan spesifikasi otorisasi MCP, dibandingkan dengan dokumentasi Claude Code untuk menyambungkan dan membatasi server. Saya belum menjalankannya di stack asli untuk tulisan ini, jadi setiap perilaku di bawah saya kaitkan ke halaman yang menyatakannya, dan bila itu hanya dugaan saya, saya bilang begitu.

Tiga scope, dan apa yang ditambahkan tiap level

Server ini adalah endpoint hosted di https://mcp.grafana.com/mcp dan bersifat user-scoped: agent hanya mendapat permission yang diberikan RBAC Grafana kepada Anda. Di atas itu, halaman consent menanyakan seberapa banyak akses Anda yang mau diserahkan ke client ini. Dokumentasi mendefinisikan tiga level, masing-masing mencakup level di bawahnya.

Ada dua detail role di balik halaman consent. Untuk terhubung sama sekali Anda butuh role Assistant Cloud MCP User atau permission grafana-assistant-app.cloud-mcp:access, yang secara default dimiliki Editor ke atas. Write butuh lebih: Organization Admin punya secara default, dan yang lain perlu role Assistant Admin.

Query bukan read, dan mematikan Write saja membuktikannya

Kalimat terpenting di dokumentasi scope adalah soal read-only: untuk koneksi read-only Anda harus mengosongkan Write dan Query. Mengosongkan Write saja tetap mengizinkan raw SQL jika Query dipilih. Urutannya kumulatif, tetapi kotak di halaman consent terpisah, jadi mudah berakhir dengan koneksi yang tampak hati-hati padahal tidak.

Alasannya ada di definisi Query sendiri: raw SQL dijalankan apa adanya dan bisa mengubah data. Orang di depan SQL console paham itu. Agent yang menyusun statement dari skema yang setengah terbaca adalah risiko lain, dan nama scope Query tidak mengumumkannya. Saat memutuskan apa yang diberikan ke coding agent, saya memperlakukan Query sebagai level pertama yang bisa mengubah state, bukan level terakhir yang tidak bisa.

Menyambungkan Claude Code, satu entry per stack

Claude Code menambahkan server remote dengan claude mcp add dan transport http. Halaman Grafana menunjukkan bentuk satu baris, dan bentuk yang meneruskan stack Anda lewat header X-Grafana-URL supaya browser langsung ke halaman consent. Untuk lebih dari satu stack, halamannya eksplisit: pakai satu entry per stack dengan stack di path endpoint, dan jangan pakai endpoint yang sama dengan header berbeda, karena Cursor dan Claude Code menganggapnya duplikat.

# Right: one entry per stack, the stack in the endpoint path.
# --scope project writes .mcp.json so the team shares the endpoint;
# each person still authorises with their own Grafana identity.
claude mcp add grafana-prod https://mcp.grafana.com/mcp/<prod-stack>.grafana.net \
  --transport http --scope project
claude mcp add grafana-staging https://mcp.grafana.com/mcp/<staging-stack>.grafana.net \
  --transport http --scope project

# Wrong: the same endpoint twice, told apart only by a header.
# Cursor and Claude Code treat these as duplicates of one server.
claude mcp add grafana-a https://mcp.grafana.com/mcp --transport http \
  --header "X-Grafana-URL: https://<prod-stack>.grafana.net"
claude mcp add grafana-b https://mcp.grafana.com/mcp --transport http \
  --header "X-Grafana-URL: https://<staging-stack>.grafana.net"

# Authenticate. --no-browser prints the URL, handy over SSH.
claude mcp login grafana-prod --no-browser

# Inside a session, /mcp shows status and lets you re-authenticate.
claude mcp list

Autentikasi lalu terjadi di browser. Di dalam Claude Code Anda menjalankan /mcp dan menyelesaikan login, atau dari shell memakai claude mcp login dengan nama server; flag --no-browser mencetak URL dan meminta Anda menempelkan redirect kembali, yang cocok dipakai lewat SSH. Lokasi entry juga penting: scope local adalah default dan privat untuk Anda, sedangkan scope project menulis .mcp.json yang bisa di-commit, jadi tim berbagi endpoint tetapi tiap orang tetap memberi otorisasi dengan identitas Grafana masing-masing.

Cursor, VS Code, dan client lain

Semua client di halaman Grafana memakai endpoint yang sama dan transport Streamable HTTP; bedanya hanya file config dan apakah key transport disebut type. Cursor dan Windsurf memakai url dan headers, sementara Claude Desktop dan VS Code menambahkan type http secara eksplisit, dan VS Code menaruh semuanya di bawah servers, bukan mcpServers.

// .cursor/mcp.json  (Windsurf is the same shape)
{
  "mcpServers": {
    "grafana": {
      "url": "https://mcp.grafana.com/mcp",
      "headers": { "X-Grafana-URL": "https://<your-stack>.grafana.net" }
    }
  }
}

// .vscode/mcp.json  (note "servers", and the explicit type)
{
  "servers": {
    "grafana": {
      "type": "http",
      "url": "https://mcp.grafana.com/mcp",
      "headers": { "X-Grafana-URL": "https://<your-stack>.grafana.net" }
    }
  }
}

Streamable HTTP adalah satu-satunya transport. SSE tidak didukung server, dan Claude Code sendiri menandai transport sse-nya sebagai deprecated, jadi tidak ada fallback kalau sebuah client hanya bisa SSE. Server ini juga hanya untuk Grafana Cloud; Grafana self-hosted butuh server open source lokal, yang dibandingkan di bagian tujuh.

Satu jam, tiga puluh hari, dan artinya untuk automation

Masa berlaku yang terdokumentasi sederhana. Access token berlaku satu jam dan di-refresh otomatis. Session berlangsung 30 hari; setelah itu Anda harus login dan memberi otorisasi ulang. Seseorang bisa mencabut koneksi di Settings, Connectors, MCP clients, Your connections. Untuk sesi coding interaktif ini tak terlihat, dan sejalan dengan spesifikasi otorisasi MCP: authorization server sebaiknya menerbitkan access token berumur pendek, dan untuk public client wajib merotasi refresh token.

Untuk automation tanpa pengawasan, baris yang menarik ada di halaman registrasi client Grafana: client yang tidak mendukung Dynamic Client Registration atau Client ID Metadata Documents butuh client yang didaftarkan manual. Assistant Admin mendaftarkannya di Assistant, Settings, Connectors, MCP clients, memilih akses maksimum yang boleh diberikan, lalu menyalin client ID dan secret, yang hanya ditampilkan sekali oleh Grafana. Client harus mendukung Streamable HTTP dan authorization code flow dengan PKCE memakai S256.

# After an Assistant Admin registers a client (Assistant > Settings >
# Connectors > MCP clients > OAuth clients > Register client), pass its
# credentials to Claude Code. --client-secret prompts with masked input;
# in CI set MCP_CLIENT_SECRET instead.
# The redirect URL registered in Grafana must match exactly:
#   http://localhost:8080/callback   (HTTP is allowed only for loopback)
claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  grafana-ci https://mcp.grafana.com/mcp/<stack>.grafana.net

Registrasi itu mengidentifikasi aplikasi, bukan user. Tiap orang tetap login dan memberi otorisasi koneksinya sendiri dengan permission Grafana miliknya, dan mendaftarkan client tidak memberi akses data apa pun. Halaman itu tidak membahas service account atau penggunaan headless, jadi saya tidak akan menjanjikan akun bot ke tim lewat jalur ini. Yang diberikan adalah batas atas: pengaturan allowed access membatasi apa yang bisa diberikan user mana pun, dan mengubahnya hanya berlaku untuk otorisasi baru.

Tambahkan rule sisi client di atas halaman consent

Consent adalah kontrol sisi server dan deny rule adalah kontrol sisi client; saya ingin keduanya. Claude Code menamai tool MCP mcp__server__tool dan membiarkan permission rule mencocokkan nama persis itu. Deny rule mengeluarkan tool dari yang bisa dipanggil model, apa pun yang akan diizinkan server. Perhatikan bahwa rule dengan tanda kurung dilewati untuk tool mcp__, jadi pakai nama polos.

// .claude/settings.json
// The server segment must match the name you gave "claude mcp add".
// Use plain tool names: mcp__ rules containing parentheses are skipped.
{
  "permissions": {
    "allow": [
      "mcp__grafana-prod__search_dashboards",
      "mcp__grafana-prod__list_datasources",
      "mcp__grafana-prod__query_prometheus",
      "mcp__grafana-prod__query_loki_logs"
    ],
    "deny": [
      "mcp__grafana-prod__update_dashboard",
      "mcp__grafana-prod__create_folder",
      "mcp__grafana-prod__create_annotation",
      "mcp__grafana-prod__update_annotation",
      "mcp__grafana-prod__create_incident",
      "mcp__grafana-prod__add_activity_to_incident",
      "mcp__grafana-prod__create_investigation",
      "mcp__grafana-prod__ask_assistant"
    ]
  }
}

Ada satu jebakan yang datang dari daftar tool, bukan dari satu kalimat tertentu. alerting_manage_rules ditandai Read dan Write dalam satu tool, jadi deny level tool akan menghapus pembacaan alert bersama pengeditannya. Itu dugaan saya dari tabel, bukan perilaku terdokumentasi, dan karena itu saya tidak mengandalkan deny rule saja: scope consent adalah kontrol yang memisahkan read dari write di dalam satu tool, dan deny list menutup tool yang jelas write-only.

Cloud MCP atau server open source

Grafana punya dua server, dan pilihannya kebanyakan soal siapa yang memegang credential. Yang hosted memakai OAuth dan user-scoped; mcp-grafana open source berjalan di tempat Anda menjalankannya dan autentikasi dengan service account token lewat GRAFANA_SERVICE_ACCOUNT_TOKEN, bersama GRAFANA_URL.

Pertukarannya adalah audit melawan kemudahan. Dengan server hosted, setiap query berjalan atas nama manusia yang jelas, dan itu properti yang saya mau dari tool yang dikemudikan AI. Service account token bersama lebih mudah di-script dan lebih sulit diatribusikan. Saya memilih yang pertama untuk eksplorasi dan yang kedua hanya dengan akun yang sengaja dibuat sempit.

Yang dikerjakan hari Senin

Tidak satu pun butuh infrastruktur baru. Yang dibutuhkan adalah beberapa keputusan sengaja sebelum koneksi pertama, karena default halaman consent bukan milik Anda.

1. Pastikan stack-nya Grafana Cloud dan Anda memegang role Assistant Cloud MCP User atau permission cloud-mcp:access.
2. Tambahkan satu server per stack di scope project, dinamai sesuai environment, dengan stack di path endpoint.
3. Beri otorisasi production dengan Write dan Query dikosongkan. Naikkan ke Query hanya untuk tugas tertentu, di staging dulu.
4. Commit blok permissions yang men-deny tool write-only berdasarkan nama mcp__ mereka.
5. Kalau CI ingin memakainya, minta Assistant Admin mendaftarkan client dengan batas Read only, dan rencanakan otorisasi ulang tiap 30 hari.

Lalu ajukan satu pertanyaan read yang jawabannya sudah Anda tahu, misalnya error rate saat ini dari sebuah service, dan bandingkan. Kalau angka agent cocok dengan dashboard Anda, jalurnya terbukti ujung ke ujung sebelum Anda percayakan ke pertanyaan yang belum dikenal.

Nama scope adalah janji tentang halaman consent, bukan tentang agent, dan aturan yang berguna adalah memberi level paling kecil yang menjawab pertanyaan: Read untuk eksplorasi, Query hanya untuk tugas tertentu, Write hampir tidak pernah, dengan deny rule dan session pendek di belakangnya.