Grafana

Serveur MCP Grafana

Un serveur Model Context Protocol (MCP) pour Grafana.

Il permet d’accéder à votre instance Grafana et à l’écosystème qui l’entoure.

Démarrage rapide

Nécessite uv. Ajoutez ce qui suit à la configuration de votre client MCP (par exemple, Claude Desktop ou Cursor) :

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

Pour Grafana Cloud, remplacez GRAFANA_URL par l’URL de votre instance (par exemple, https://myinstance.grafana.net). Consultez Utilisation pour découvrir d’autres options d’installation, notamment Docker, les binaires et Helm.

Prérequis

• Grafana version 9.0 ou ultérieure est nécessaire pour bénéficier de toutes les fonctionnalités. Certaines fonctionnalités, en particulier les opérations liées aux sources de données, peuvent ne pas fonctionner correctement avec les versions antérieures en raison de l’absence de points de terminaison d’API.

Fonctionnalités

Les fonctionnalités suivantes sont actuellement disponibles dans le serveur MCP. Cette liste est fournie à titre informatif uniquement et ne constitue ni une feuille de route ni un engagement concernant de futures fonctionnalités.

Tableaux de bord

• Rechercher des tableaux de bord : Trouver des tableaux de bord par titre, UID de dossier, étiquette ou statut favori
• Obtenir un tableau de bord par UID : Récupérer tous les détails d’un tableau de bord à l’aide de son identifiant unique. Transmettez éventuellement version pour charger un instantané enregistré plutôt que le tableau de bord actuel. Attention : les tableaux de bord volumineux peuvent consommer une grande partie de la fenêtre de contexte.
• Lister les versions d’un tableau de bord : Lister les versions enregistrées d’un tableau de bord sous forme de métadonnées compactes (numéro de version, auteur, horodatage, message d’enregistrement)
• Obtenir un résumé du tableau de bord : Obtenir une vue d’ensemble compacte d’un tableau de bord, comprenant le titre, le nombre de panneaux, les types de panneaux, les variables et les métadonnées, sans le JSON complet, afin de réduire l’utilisation de la fenêtre de contexte
• Obtenir une propriété du tableau de bord : Extraire des parties spécifiques d’un tableau de bord à l’aide d’expressions JSONPath (par exemple, $.title, $.panels[*].title) pour ne récupérer que les données nécessaires et réduire l’utilisation de la fenêtre de contexte
• Mettre à jour ou créer un tableau de bord : Modifier des tableaux de bord existants ou en créer de nouveaux. Attention : cette opération nécessite le JSON complet du tableau de bord, ce qui peut consommer une grande partie de la fenêtre de contexte.
• Appliquer un correctif à un tableau de bord : Appliquer des modifications spécifiques à un tableau de bord sans avoir besoin du JSON complet, ce qui réduit considérablement l’utilisation de la fenêtre de contexte pour les modifications ciblées
• Obtenir les requêtes des panneaux et les informations sur les sources de données : Obtenir le titre, la chaîne de requête et les informations sur la source de données (y compris l’UID et le type, si disponibles) de chaque panneau d’un tableau de bord

Exécuter une requête de panneau

Remarque : Les outils d’exécution de requêtes de panneau sont désactivés par défaut. Pour les activer, ajoutez runpanelquery à l’indicateur --enabled-tools.

• Exécuter une requête de panneau : Exécuter la requête d’un panneau de tableau de bord avec des plages temporelles personnalisées et des substitutions de variables. Les panneaux Infinity s’exécutent lorsque la requête utilise l’analyseur backend ou jq-backend (les requêtes Google Sheets le font toujours) ; l’analyseur par défaut simple ainsi que les analyseurs UQL et GROQ ne fonctionnent que dans le navigateur. Les panneaux Neo4j du plug-in kniepdennis-neo4j-datasource exécutent leur requête Cypher via le plug-in, qui ouvre des sessions en lecture seule. Les panneaux Elasticsearch interpolent les variables dans la requête Lucene au format lucene, comme le fait Grafana, et les histogrammes de dates automatiques utilisent le même intervalle que $__interval.

Gestion de la fenêtre de contexte

Les outils de tableau de bord incluent désormais plusieurs stratégies pour gérer efficacement l’utilisation de la fenêtre de contexte (issue #101) :

• Utilisez get_dashboard_summary pour obtenir une vue d’ensemble du tableau de bord et planifier des modifications
• Utilisez get_dashboard_property avec JSONPath lorsque seules certaines parties du tableau de bord sont nécessaires
• Évitez get_dashboard_by_uid, sauf si vous avez spécifiquement besoin du JSON complet du tableau de bord

Sources de données

• Lister et récupérer les informations sur les sources de données : Afficher toutes les sources de données configurées et récupérer des informations détaillées sur chacune d’elles.
  • Types de sources de données pris en charge : Prometheus, Loki, ClickHouse, CloudWatch, Elasticsearch, OpenSearch, Snowflake, Athena.
• Ressources des sources de données : Chaque source de données à laquelle vous pouvez accéder est également exposée en tant que ressource MCP à l’adresse grafana://datasources/{uid}, afin que vous puissiez l’ajouter directement à une conversation (par exemple avec @ dans Claude Code) au lieu de laisser le modèle la rechercher. Désactivé en même temps que les outils de source de données.

Exemples de requêtes

Remarque : Les outils d’exemples de requêtes sont désactivés par défaut. Pour les activer, ajoutez examples à l’indicateur --enabled-tools.

• Obtenir des exemples de requêtes : Récupérer des exemples de requêtes pour différents types de sources de données afin d’en apprendre la syntaxe.

Requêtes Prometheus

• Interroger Prometheus : Exécuter des requêtes PromQL (prenant en charge les requêtes de métriques instantanées et sur une plage) sur des sources de données Prometheus.
• Interroger les métadonnées Prometheus : Récupérer les métadonnées des métriques, les noms des métriques, les noms des étiquettes et les valeurs des étiquettes depuis des sources de données Prometheus.
• Interroger les percentiles d’histogramme : Calculer les valeurs des percentiles d’histogramme (p50, p90, p95, p99) à l’aide de histogram_quantile.

Requêtes Loki

• Interroger les journaux et les métriques Loki : Exécuter des requêtes de journaux et de métriques avec LogQL sur des sources de données Loki.
• Interroger les métadonnées Loki : Récupérer les noms des étiquettes, leurs valeurs et les statistiques des flux depuis des sources de données Loki.
• Interroger les motifs Loki : Récupérer les motifs de journaux détectés par Loki afin d’identifier les structures de journaux courantes et les anomalies.

Requêtes InfluxDB

Remarque : Les outils InfluxDB sont désactivés par défaut. Pour les activer, ajoutez influxdb à l’indicateur --enabled-tools.

• Interroger InfluxDB : Exécuter des requêtes sur des sources de données InfluxDB avec InfluxQL (v1.x) ou Flux (v2.x). Le dialecte est déduit de la configuration de la source de données, ou peut être défini explicitement à l’aide du paramètre dialect.

Requêtes sur les sources de données SQL

Remarque : Les outils SQL sont désactivés par défaut. Pour les activer, ajoutez sql à l’indicateur --enabled-tools. Les alias rétrocompatibles clickhouse, snowflake et athena fonctionnent également.

Les outils SQL unifiés prennent en charge ClickHouse, Snowflake, Athena, MySQL, PostgreSQL, MSSQL et BigQuery au moyen d’un ensemble unique d’outils. Les requêtes passent par les plug-ins de source de données de Grafana ; l’authentification est donc gérée par la configuration de la source de données — les identifiants ne sont jamais accessibles au serveur MCP.

• Lister les bases de données/schémas/catalogues : Découvrir les unités organisationnelles d’une source de données SQL. Pour Athena, omettez le catalogue pour lister les catalogues, ou indiquez-en un pour lister les bases de données.
• Lister les tables : Lister les tables d’une base de données ou d’un schéma avec leurs métadonnées (nombre de lignes, tailles lorsqu’elles sont disponibles).
• Décrire le schéma d’une table : Obtenir les noms des colonnes, leurs types, leur nullabilité, leurs valeurs par défaut et leurs commentaires.
• Interroger SQL : Exécuter des requêtes SQL avec substitution de macros propre à chaque source de données ($__timeFilter(col), $__from/$__to, $__interval, ${varname}), application automatique d’une limite et prise en charge des variables de modèle.

Pour BigQuery, configurez le plug-in grafana-bigquery-datasource dans Grafana. La découverte utilise database pour le projet et schema pour le jeu de données. Si database est omis, le projet prend par défaut la valeur de la source de données defaultProject, puis celle du point de terminaison /defaultProjects du plug-in (y compris la découverte du projet GCE). Les métadonnées sont récupérées uniquement via des API, sans tâches de requête ni balayage de tables. Les descriptions de colonnes et les types imbriqués sont inclus ; le plug-in omet les descriptions et les types des tables, la nullabilité des colonnes et les valeurs par défaut.

Les requêtes BigQuery nécessitent des références de tables qualifiées, telles que `my-project.my_dataset.fct_events` and use the datasource's billing project. Optional location defaults to datasource processingLocation. Use ${name:sqlstring} pour les variables de chaîne échappées. Les limites de lignes ne limitent ni les octets analysés ni le coût des requêtes.

Requêtes CloudWatch

Remarque : Les outils CloudWatch sont désactivés par défaut. Pour les activer, ajoutez cloudwatch à l’indicateur --enabled-tools.

• Lister les espaces de noms CloudWatch : Découvrir les espaces de noms AWS CloudWatch disponibles.
• Lister les métriques CloudWatch : Lister les métriques disponibles dans un espace de noms donné.
• Lister les dimensions CloudWatch : Obtenir les dimensions permettant de filtrer les requêtes de métriques.
• Interroger CloudWatch : Exécuter des requêtes de métriques CloudWatch avec prise en charge des plages temporelles.
• Lister les groupes de journaux CloudWatch : Découvrir les groupes de journaux, avec un filtrage facultatif par préfixe de nom.
• Lister les champs des groupes de journaux CloudWatch : Découvrir les champs disponibles dans un groupe de journaux.
• Interroger CloudWatch Logs : Exécuter des requêtes CloudWatch Logs Insights sur un ou plusieurs groupes de journaux.

Requêtes Google Cloud Logging

Remarque : Les outils Google Cloud Logging sont désactivés par défaut. Pour les activer, ajoutez cloudlogging à l’indicateur --enabled-tools. Nécessite le plug-in de source de données Google Cloud Logging (googlecloud-logging-datasource) version 1.8.0 ou ultérieure, qui requiert Grafana 11.2 ou une version ultérieure. Les anciennes versions du plug-in renvoient une structure de réponse différente et query_cloud_logging signale une erreur demandant une mise à niveau.

• Lister les projets Cloud Logging : Découvrir les ID de projets GCP depuis lesquels la source de données peut lire les journaux.
• Lister les buckets et les vues Cloud Logging : Découvrir les buckets de journaux et les vues de journaux afin de délimiter une requête.
• Interroger Cloud Logging : Exécuter des filtres du langage de requête Cloud Logging (par exemple, resource.type="k8s_container" AND severity>=ERROR) avec une plage temporelle et une limite ; renvoie les entrées de la plus récente à la plus ancienne, avec leur gravité, leur corps, leurs étiquettes et leur ID de trace. L’authentification GCP est gérée par la configuration de la source de données.

Requêtes Graphite

Remarque : Les outils Graphite sont désactivés par défaut. Pour les activer, ajoutez graphite à l’indicateur --enabled-tools.

• Interroger Graphite : Exécuter des requêtes de l’API render Graphite sur une source de données Graphite.
• Lister les métriques Graphite : Parcourir et découvrir les chemins des métriques Graphite.
• Lister les étiquettes Graphite : Lister les étiquettes Graphite disponibles et leurs valeurs.
• Interroger la densité Graphite : Interroger la densité des métriques Graphite pour un motif donné.

Requêtes Elasticsearch/OpenSearch

Remarque : Les outils Elasticsearch/OpenSearch sont désactivés par défaut. Pour les activer, ajoutez elasticsearch à l’indicateur --enabled-tools.

• Interroger Elasticsearch/OpenSearch : Exécuter des requêtes de recherche sur des sources de données Elasticsearch ou OpenSearch à l’aide de la syntaxe de requête Lucene ou de l’Elasticsearch Query DSL. Prend en charge le filtrage par plage temporelle et la récupération de journaux, de métriques ou de toute donnée indexée. Renvoie les documents avec leur index, leur ID, leurs champs source et, éventuellement, leur score de pertinence.

Requêtes Quickwit

Remarque : Les outils Quickwit sont désactivés par défaut. Pour les activer, ajoutez quickwit à l’indicateur --enabled-tools.

• Interroger Quickwit : Exécuter des requêtes de recherche sur des sources de données Quickwit à l’aide de la syntaxe de requête Lucene ou d’un sous-ensemble du Query DSL compatible avec Elasticsearch. Prend en charge le filtrage par plage temporelle et la récupération de journaux ou d’autres documents indexés. Renvoie les documents avec leur index, leur ID, leurs champs source et, éventuellement, leur score de pertinence.

Observabilité des agents

Remarque : Les outils d’observabilité des agents sont désactivés par défaut et ne fonctionnent que dans Grafana Cloud. Pour les activer, ajoutez agento11y à l’indicateur --enabled-tools.

• Lister et rechercher des conversations : Lister les conversations récentes avec un LLM ou les rechercher à l’aide d’une expression de filtre (modèle, fournisseur, agent, statut, type d’erreur, résultats d’évaluation, etc.) sur une période donnée. Les résultats de recherche incluent le nombre d’erreurs, des résumés des évaluations et des notes, ainsi que les ID de trace.
• Obtenir les détails d’une conversation : Récupérer une conversation avec toutes ses générations, y compris les prompts et les sorties.
• Obtenir les détails et les scores d’une génération : Récupérer une génération par ID et ses scores d’évaluation (évaluateur, clé du score, valeur, réussite, explication).
• Lire le catalogue des agents : Lister les agents qui envoient des données de télémétrie, récupérer intégralement une version d’agent (prompt système complet, tous les outils avec leur schéma JSON et les modèles utilisés), parcourir l’historique des versions d’un agent et comparer les agrégats des scores d’évaluation par version. Les versions effectives sont des hachages sha256: qu’une modification d’outil n’affecte jamais ; pour un agent qui ne déclare pas sa propre version, le hachage est calculé à partir du prompt système, de sorte qu’une modification du prompt crée une nouvelle version. Les lignes du catalogue et des versions comportent un token_estimate, qu’il est utile de vérifier avant de récupérer un prompt complet.
• Inspecter les évaluateurs et les modèles : Lire les évaluateurs à l’origine d’un score, les modèles dont ils sont dérivés, ainsi que les fournisseurs et modèles de juge disponibles pour les évaluateurs utilisant un LLM comme juge. Lorsque les outils d’écriture sont activés, créer, dériver, tester et supprimer des évaluateurs.
• Inspecter les règles d’évaluation et les garde-fous : Lire les règles d’évaluation asynchrones qui associent des évaluateurs au trafic de production, ainsi que les garde-fous (règles de hook) exécutés en ligne et capables d’émettre un avertissement ou de refuser une requête. Lorsque les outils d’écriture sont activés, les créer, les mettre à jour, les prévisualiser et les supprimer. Les opérations d’écriture et les opérations preview_rule et test_evaluator qui ne persistent pas nécessitent l’autorisation grafana-agento11y-app.eval:write, accordée par le rôle Agento11y Admin.
• Organiser les conversations et collections enregistrées : Lire les conversations enregistrées (signets qui attribuent à une conversation un ID stable, un nom et des tags) et les collections qui les regroupent, y compris le nombre de membres de chaque collection et les collections intégrées à chaque ligne de conversation enregistrée. Lorsque les outils d’écriture sont activés, ajouter aussi une conversation aux signets, créer et modifier des collections, et ajouter ou supprimer des membres. Ces opérations d’écriture nécessitent la même autorisation grafana-agento11y-app.eval:write.
• Lire et modifier les suites de tests : Lister les suites de tests versionnées utilisées par les expériences hors ligne, lire une suite avec l’historique complet de ses versions et parcourir les cas de test d’une version. Lorsque les outils d’écriture sont activés, créer une suite, la renommer ou modifier ses tags, ouvrir une version brouillon, la publier, et créer ou supprimer ses cas de test. Une version publiée est figée ; toute modification nécessite donc l’ouverture d’un nouveau brouillon. Ces opérations d’écriture nécessitent grafana-agento11y-app.eval:write.
• Lire les expériences hors ligne : Lister les exécutions d’évaluation d’une suite de tests et en lire une avec son taux de réussite global, son coût et le nombre total de jetons. Examiner le rapport par cas de test, puis les essais, leurs scores accompagnés de l’explication de chaque juge et les métadonnées de leurs artefacts. Lorsque les outils d’écriture sont activés, renommer une expérience ou modifier ses tags, et annuler une expérience en cours d’exécution ; ces opérations nécessitent grafana-agento11y-app.eval:write. Les expériences sont créées par des exécuteurs du SDK, et non par cet outil.

Grafana Assistant

Remarque : Les outils de l’assistant sont désactivés par défaut et nécessitent l’installation du plugin Grafana Assistant (grafana-assistant-app) sur l’instance Grafana cible. Ce sont également des outils d’écriture (l’assistant peut modifier l’état de la stack) ; ils sont donc ignorés lorsque --disable-write est défini. Pour les activer, ajoutez assistant à votre indicateur --enabled-tools.

• Interroger l’assistant : Envoyer un prompt en langage naturel à Grafana Assistant et attendre sa réponse complète. L’assistant peut utiliser des outils, des métriques, des journaux et d’autres éléments de contexte de la stack — un périmètre plus large que celui d’une seule requête isolée à une source de données. Renvoyez le contextId obtenu lors d’un appel ultérieur pour poursuivre la même conversation. Les tâches complexes peuvent prendre plusieurs minutes ; l’appel reste bloqué jusqu’à la fin de la réponse ou jusqu’à l’expiration du délai de la requête (5 minutes).

Incidents

• Rechercher, créer et mettre à jour des incidents : Gérer les incidents dans Grafana Incident, notamment en les recherchant, en les créant, en ajoutant des activités et en lisant ou définissant des champs personnalisés.
• Ressources d’incident : Les incidents actifs ayant commencé au cours des 30 derniers jours sont également exposés en tant que ressources MCP à l’adresse grafana://irm/incidents/{id}, afin que vous puissiez en joindre un directement à une conversation (par exemple avec @ dans Claude Code). Cette fonctionnalité est désactivée en même temps que les outils d’incident.

Alerting

• Lister et récupérer les informations sur les règles d’alerte : Consulter les règles d’alerte et leur état (en alerte/normal/erreur/etc.) dans Grafana. Prend en charge les règles gérées par Grafana et celles gérées par les sources de données Prometheus ou Loki.
• Créer et mettre à jour des règles d’alerte : Créer de nouvelles règles d’alerte ou modifier celles qui existent.
• Supprimer des règles d’alerte : Supprimer des règles d’alerte par UID.
• Gérer le routage des alertes : Consulter les politiques de notification, les points de contact et les intervalles de temps. Prend en charge les points de contact gérés par Grafana et les récepteurs de sources de données Alertmanager externes (Prometheus Alertmanager, Mimir, Cortex).

Grafana OnCall

• Lister et gérer les plannings : Consulter et gérer les plannings d’astreinte dans Grafana OnCall.
• Obtenir les détails d’une rotation : Récupérer des informations détaillées sur des rotations d’astreinte spécifiques.
• Obtenir les utilisateurs actuellement d’astreinte : Voir quels utilisateurs sont actuellement d’astreinte pour un planning.
• Lister les équipes et les utilisateurs : Consulter toutes les équipes et tous les utilisateurs OnCall.
• Lister les groupes d’alertes : Consulter et filtrer les groupes d’alertes de Grafana OnCall selon différents critères, notamment l’état, l’intégration, les libellés et la période.
• Obtenir les détails d’un groupe d’alertes : Récupérer des informations détaillées sur un groupe d’alertes spécifique à partir de son ID.

Admin

Remarque : Les outils d’administration sont désactivés par défaut. Pour les activer, incluez admin dans votre indicateur --enabled-tools.

• Lister les équipes : Consulter toutes les équipes configurées dans Grafana.
• Lister les utilisateurs : Consulter tous les utilisateurs d’une organisation dans Grafana.
• Lister tous les rôles : Lister tous les rôles Grafana, avec un filtre facultatif pour les rôles délégables.
• Obtenir les détails d’un rôle : Obtenir les détails d’un rôle Grafana spécifique à partir de son UID.
• Lister les attributions d’un rôle : Lister tous les utilisateurs, équipes et comptes de service auxquels un rôle est attribué.
• Lister les rôles des utilisateurs : Lister tous les rôles attribués à un ou plusieurs utilisateurs.
• Lister les rôles des équipes : Lister tous les rôles attribués à une ou plusieurs équipes.
• Lister les autorisations d’une ressource : Lister toutes les autorisations définies pour une ressource spécifique (tableau de bord, source de données, dossier, etc.).
• Décrire une ressource Grafana : Lister les autorisations disponibles et les capacités d’attribution pour un type de ressource.

User

• Informations utilisateur : Obtenir l’identité Grafana actuelle — identifiant de connexion, adresse e-mail, nom, statut d’administrateur Grafana (serveur), organisation actuelle et organisations auxquelles l’identifiant peut accéder (avec les rôles). Utilisez cette fonction pour découvrir les valeurs orgId valides pour les requêtes multi-organisation.

Navigation

• Générer des liens profonds : Créer des URL de liens profonds exactes vers les ressources Grafana au lieu de se fier aux suppositions d’URL du LLM.
  • Liens vers les tableaux de bord : Générer des liens directs vers les tableaux de bord à l’aide de leur UID (par exemple, http://localhost:3000/d/dashboard-uid)
  • Liens vers les panneaux : Créer des liens vers des panneaux spécifiques dans les tableaux de bord avec le paramètre viewPanel (par exemple, http://localhost:3000/d/dashboard-uid?viewPanel=5)
  • Liens vers Explore : Générer des liens vers Grafana Explore avec des sources de données préconfigurées (par exemple, http://localhost:3000/explore?schemaVersion=1&panes={"a":{"datasource":"prometheus-uid"}}). Les versions de Grafana antérieures à 10.2 ne reconnaissent pas panes ; le format historique ?left={...} est donc utilisé pour ces versions.
  • Prise en charge des plages temporelles : Ajouter des paramètres de plage temporelle aux liens (from=now-1h&to=now)
  • Paramètres personnalisés : Inclure des paramètres de requête supplémentaires, comme des variables de tableau de bord ou des intervalles d’actualisation

Annotations

• Obtenir des annotations : Rechercher des annotations à l’aide de filtres. Prend en charge la plage temporelle, l’UID du tableau de bord, les tags et le mode de correspondance.
• Créer une annotation : Créer une annotation sur un tableau de bord ou un panneau.
• Créer une annotation Graphite : Créer des annotations au format Graphite (what, when, tags, data).
• Mettre à jour une annotation : Remplacer tous les champs d’une annotation existante (mise à jour complète).
• Modifier partiellement une annotation : Mettre à jour uniquement certains champs d’une annotation (mise à jour partielle).
• Supprimer une annotation : Supprimer définitivement une annotation par ID.
• Obtenir les tags d’annotation : Lister les tags d’annotation disponibles, avec un filtrage facultatif.

Snapshots

• Lister les snapshots : Lister les snapshots de tableaux de bord avec des filtres facultatifs de requête et de limite.
• Obtenir un snapshot : Récupérer les métadonnées du snapshot et le contenu du tableau de bord à partir de sa clé.
• Créer un snapshot : Créer un snapshot de tableau de bord à partir d’un contenu complet de tableau de bord, avec des options facultatives d’expiration et de snapshot externe.
• Supprimer un snapshot : Supprimer un snapshot à partir de sa clé.

Rendering

• Obtenir une image de panneau ou de tableau de bord : Générer une image PNG d’un panneau Grafana ou d’un tableau de bord complet. Renvoie l’image sous forme de données encodées en base64, utilisables dans des rapports, des alertes ou des présentations. Par défaut, les dimensions sont de 1000×750 pixels CSS pour un panneau ou de 1200×900 pour un tableau de bord complet, dans les deux cas à l’échelle 1. Pour Explore, les dimensions par défaut sont de 1000×1000 à l’échelle 1. Les dimensions sont soumises aux limites de la zone d’affichage du moteur de rendu d’images. Permet de personnaliser les dimensions, la plage temporelle, le thème, l’échelle et les variables du tableau de bord. Permet également de générer des images de tableaux de bord pas encore appliqués à partir d’une branche d’un dépôt de provisionnement (par exemple, un aperçu de PR git-sync) via le paramètre facultatif provisioningPreview.
  • Remarque : nécessite l’installation et la configuration du service Grafana Image Renderer.

Provisioning

• Lister les dépôts de provisionnement : Lister les dépôts de provisionnement configurés pour cette instance Grafana (par exemple, les sources git-sync) et renvoyer le slug de chaque dépôt, ainsi que son URL source, sa branche, son chemin, son état de synchronisation et son état de santé.
• Valider un fichier de provisionnement : Effectuer une simulation d’application d’un fichier provenant d’un dépôt de provisionnement sur une branche ou un commit donné. Indique si le fichier serait accepté, l’action sur la ressource (création/mise à jour), le type de ressource cible et les éventuelles erreurs de validation structurées — la même interface de validation que celle utilisée par le commentateur de PR de Grafana.

La liste des outils est configurable ; vous pouvez donc choisir ceux que vous souhaitez mettre à la disposition du client MCP. Cette option est utile si vous n’utilisez pas certaines fonctionnalités ou si vous souhaitez éviter de trop solliciter la fenêtre de contexte. Pour désactiver une catégorie d’outils, utilisez l’indicateur --disable-<category> au démarrage du serveur. Par exemple, pour désactiver les outils OnCall, utilisez --disable-oncall, ou pour désactiver la génération de liens profonds de navigation, utilisez --disable-navigation.

Autorisations RBAC

Chaque outil nécessite des autorisations RBAC spécifiques pour fonctionner correctement. Lors de la création d’un compte de service pour le serveur MCP, assurez-vous qu’il dispose des autorisations nécessaires selon les outils que vous prévoyez d’utiliser. Les autorisations répertoriées correspondent aux actions minimales requises ; des portées appropriées peuvent également être nécessaires (par exemple, datasources:*, dashboards:*, folders:*), selon votre cas d’utilisation.

Conseil : Si vous ne connaissez pas bien le RBAC de Grafana ou si vous préférez une configuration plus rapide et plus simple plutôt que de définir de nombreuses portées granulaires, vous pouvez attribuer au compte de service un rôle intégré tel que Editor. Le rôle Editor accorde un accès étendu en lecture et en écriture, qui permet la plupart des opérations du serveur MCP ; il est moins granulaire (et donc moins restrictif) que des portées appliquées manuellement. Utilisez-le uniquement si la simplicité est plus importante qu’un accès strictement limité au moindre privilège.

Remarque : Les outils OnCall et les autres outils reposant sur des plugins sont autorisés par des actions de plugin telles que grafana-irm-app.schedules:read. Le rôle Viewer de base inclut les actions de lecture, et le rôle Editor, les actions d’écriture. Les outils Incident nécessitent uniquement plugins.app:access ; IRM autorise les actions d’incident en fonction du rôle de base.

Les actions au format group/resource:verb, telles que dashboard.grafana.app/dashboards:get, s’appliquent uniquement aux jetons d’accès utilisés au nom d’un utilisateur. Un compte de service n’a besoin que des autres actions répertoriées.

Pour en savoir plus sur le RBAC de Grafana, consultez la documentation officielle.

Portées RBAC

Les portées définissent les ressources spécifiques auxquelles s’appliquent les autorisations. Chaque action nécessite une combinaison appropriée d’autorisation et de portée.

Modèles de portée courants :

• Accès étendu : Utilisez les caractères génériques * pour un accès à l’échelle de l’organisation

  • datasources:* - Accès à toutes les sources de données
  • dashboards:* - Accès à tous les tableaux de bord
  • folders:* - Accès à tous les dossiers
  • teams:* - Accès à toutes les équipes

• Accès limité : Utilisez des UID ou des ID spécifiques pour restreindre l’accès à des ressources individuelles

  • datasources:uid:prometheus-uid - Accès uniquement à une source de données Prometheus spécifique
  • dashboards:uid:abc123 - Accès uniquement au tableau de bord avec l’UID abc123
  • folders:uid:xyz789 - Accès uniquement au dossier avec l’UID xyz789
  • teams:id:5 - Accès uniquement à l’équipe avec l’ID 5
  • global.users:id:123 - Accès uniquement à l’utilisateur avec l’ID 123

Exemples :

• Accès complet au serveur MCP : Accordez des autorisations étendues pour tous les outils

  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)
  

• Accès limité aux sources de données : Interrogez uniquement des instances Prometheus et Loki spécifiques

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

• Accès spécifique aux tableaux de bord : Lisez uniquement des tableaux de bord spécifiques

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

Outils

Outil	Catégorie	Description	Autorisations RBAC requises	Portées requises
list_teams	Admin*	Lister toutes les équipes	teams:read	teams:* ou teams:id:1
list_users_by_org	Admin*	Lister les utilisateurs d’une organisation, avec recherche et pagination	org.users:read	global.users:* ou global.users:id:123
list_all_roles	Admin*	Lister tous les rôles Grafana	roles:read	roles:*
get_role_details	Admin*	Obtenir les détails d’un rôle Grafana	roles:read	roles:uid:editor
get_role_assignments	Admin*	Lister les attributions d’un rôle	roles:read, teams.roles:read, users.roles:read	roles:uid:editor
list_user_roles	Admin*	Lister les rôles des utilisateurs	users.roles:read	global.users:id:123
list_team_roles	Admin*	Lister les rôles des équipes	teams.roles:read	teams:id:7
get_resource_permissions	Admin*	Lister les autorisations d’une ressource	dashboards.permissions:read, datasources.permissions:read, folders.permissions:read, serviceaccounts.permissions:read, teams.permissions:read, users.permissions:read	dashboards:uid:abcd1234
get_resource_description	Admin*	Décrire un type de ressource Grafana	dashboards.permissions:read, datasources.permissions:read, folders.permissions:read, serviceaccounts.permissions:read, teams.permissions:read, users.permissions:read	dashboards:*
user_info	User	Identité actuelle, capacités et organisations accessibles	None	—
search_dashboards	Search	Rechercher des tableaux de bord par requête, UID de dossier, chemin de dossier, étiquette ou favori	dashboards:read, folders:read	dashboards:* ou dashboards:uid:abc123
search_folders	Search	Rechercher des dossiers par titre	folders:read	folders:* ou folders:uid:xyz789
get_dashboard_by_uid	Dashboard	Obtenir un tableau de bord par uid, éventuellement une version enregistrée	dashboard.grafana.app/dashboards:get, dashboards:read, dashboards:write	dashboards:uid:abc123
list_dashboard_versions	Dashboard	Lister les versions enregistrées d’un tableau de bord (version, auteur, heure, message)	dashboards:read, dashboards:write	dashboards:uid:abc123
update_dashboard	Dashboard	Mettre à jour ou créer un tableau de bord	dashboard.grafana.app/dashboards:create, dashboard.grafana.app/dashboards:get, dashboard.grafana.app/dashboards:update, dashboards:create, dashboards:read, dashboards:write, folders:read	dashboards:*, folders:* ou folders:uid:xyz789
get_dashboard_panel_queries	Dashboard	Obtenir le titre du panneau, les requêtes, l’UID et le type de la source de données d’un tableau de bord	dashboard.grafana.app/dashboards:get, dashboards:read	dashboards:uid:abc123
run_panel_query	RunPanelQuery*	Exécuter une ou plusieurs requêtes de panneau de tableau de bord	dashboard.grafana.app/dashboards:get, dashboards:read, datasources:query, datasources:read	dashboards:uid:*, datasources:uid:*
get_dashboard_property	Dashboard	Extraire des parties spécifiques d’un tableau de bord à l’aide d’expressions JSONPath	dashboard.grafana.app/dashboards:get, dashboards:read	dashboards:uid:abc123
get_dashboard_summary	Dashboard	Obtenir un résumé compact d’un tableau de bord sans le JSON complet	dashboard.grafana.app/dashboards:get, dashboards:read	dashboards:uid:abc123
create_folder	Dashboard	Créer un dossier	folders:create, folders:read, folders:write	folders:*
list_datasources	Datasources	Lister les sources de données	datasources:read	datasources:*
get_datasource	Datasources	Obtenir une source de données par UID ou nom	datasources:read	datasources:uid:prometheus-uid
check_datasources_health	Datasources	Vérifier l’état d’une ou plusieurs sources de données	datasources:query, datasources:read	datasources:uid:*
create_datasource	Datasources	Créer une source de données	datasources:create, datasources:read	datasources:*
update_datasource	Datasources	Mettre à jour une source de données	datasources:read, datasources:write	datasources:* ou datasources:uid:abc123
get_query_examples	Examples*	Obtenir des exemples de requêtes pour un type de source de données	None	datasources:*
query_prometheus	Prometheus	Interroger des métriques avec PromQL sans ouvrir de graphique	datasources:query, datasources:read	datasources:uid:prometheus-uid
render_grafana_app	Rendering	Exécuter un outil de requête activé et afficher son résultat dans l’application Grafana interactive	datasources:query, datasources:read	datasources:* ou datasources:uid:<uid>
list_prometheus_metric_metadata	Prometheus	Lister les métadonnées des métriques	datasources:query, datasources:read	datasources:uid:prometheus-uid
list_prometheus_metric_names	Prometheus	Lister les noms de métriques disponibles	datasources:query, datasources:read	datasources:uid:prometheus-uid
list_prometheus_label_names	Prometheus	Lister les noms de labels correspondant à un sélecteur	datasources:query, datasources:read	datasources:uid:prometheus-uid
list_prometheus_label_values	Prometheus	Lister les valeurs d’un label spécifique	datasources:query, datasources:read	datasources:uid:prometheus-uid
query_prometheus_histogram	Prometheus	Calculer les valeurs des percentiles d’un histogramme	datasources:query, datasources:read	datasources:uid:prometheus-uid
list_incidents	Incident	Lister les incidents dans Grafana Incident, avec éventuellement leurs valeurs de champs personnalisés	plugins.app:access	N/A
create_incident	Incident	Créer un incident dans Grafana Incident, avec éventuellement des champs personnalisés	plugins.app:access	N/A
add_activity_to_incident	Incident	Ajouter un élément d’activité à un incident dans Grafana Incident	plugins.app:access	N/A
update_incident	Incident	Mettre à jour un incident dans Grafana Incident (statut, gravité, titre ou champs personnalisés)	plugins.app:access	N/A
get_incident	Incident	Obtenir un incident par ID, y compris ses champs personnalisés	plugins.app:access	N/A
list_incident_custom_fields	Incident	Lister les champs personnalisés configurés pour les incidents, avec leurs types et options de sélection	plugins.app:access	N/A
query_loki_logs	Loki	Interroger et récupérer des journaux avec LogQL (requêtes de journaux ou de métriques)	datasources:query, datasources:read	datasources:uid:loki-uid
list_loki_label_names	Loki	Lister tous les noms de labels disponibles dans les logs	datasources:query, datasources:read	datasources:uid:loki-uid
list_loki_label_values	Loki	Lister les valeurs d’un label de log spécifique	datasources:query, datasources:read	datasources:uid:loki-uid
query_loki_stats	Loki	Obtenir des statistiques sur les flux de logs	datasources:query, datasources:read	datasources:uid:loki-uid
query_loki_patterns	Loki	Interroger les modèles de logs détectés pour identifier les structures courantes	datasources:query, datasources:read	datasources:uid:loki-uid
analyze_loki_labels	Loki	Auditer une stratégie de labels Loki (en direct ou statique) et éventuellement diagnostiquer les performances des requêtes	datasources:query, datasources:read	datasources:uid:loki-uid
suggest_loki_alloy_label_config	Config	Générer un extrait Alloy loki.process imposant les labels approuvés	None	N/A
query_influxdb	InfluxDB*	Interroger InfluxDB avec InfluxQL (v1) ou Flux (v2)	datasources:query, datasources:read	datasources:uid:influxdb-uid
list_sql_databases	SQL*	Lister les bases de données, schémas ou catalogues d’une source de données SQL	datasources:query, datasources:read	datasources:uid:*
list_sql_tables	SQL*	Lister les tables d’une source de données SQL	datasources:query, datasources:read	datasources:uid:*
describe_sql_table	SQL*	Obtenir le schéma des colonnes d’une table	datasources:query, datasources:read	datasources:uid:*
query_sql	SQL*	Exécuter des requêtes SQL avec substitution de macros	datasources:query, datasources:read	datasources:uid:*
list_cloudwatch_namespaces	CloudWatch*	Lister les espaces de noms AWS CloudWatch disponibles	datasources:query, datasources:read	datasources:uid:*
list_cloudwatch_metrics	CloudWatch*	Lister les métriques d’un espace de noms	datasources:query, datasources:read	datasources:uid:*
list_cloudwatch_dimensions	CloudWatch*	Lister les dimensions d’une métrique	datasources:query, datasources:read	datasources:uid:*
list_cloudwatch_dimension_values	CloudWatch*	Lister les valeurs d’une clé de dimension	datasources:query, datasources:read	datasources:uid:*
query_cloudwatch	CloudWatch*	Exécuter des requêtes de métriques CloudWatch	datasources:query, datasources:read	datasources:uid:*
list_cloudwatch_log_groups	CloudWatch*	Lister les groupes de logs CloudWatch	datasources:query, datasources:read	datasources:uid:*
list_cloudwatch_log_group_fields	CloudWatch*	Lister les champs détectés dans un groupe de logs	datasources:query, datasources:read	datasources:uid:*
query_cloudwatch_logs	CloudWatch*	Exécuter des requêtes CloudWatch Logs Insights	datasources:query, datasources:read	datasources:uid:*
list_cloud_logging_projects	Cloud Logging*	Lister les projets GCP accessibles en lecture par une source de données Google Cloud Logging	datasources:query, datasources:read	datasources:uid:*
list_cloud_logging_buckets	Cloud Logging*	Lister les buckets de logs d’un projet GCP	datasources:query, datasources:read	datasources:uid:*
list_cloud_logging_views	Cloud Logging*	Lister les vues de journaux dans un bucket de journaux	datasources:query, datasources:read	datasources:uid:*
query_cloud_logging	Cloud Logging*	Interroger les journaux avec le langage de requête Cloud Logging	datasources:query, datasources:read	datasources:uid:*
query_elasticsearch	Elasticsearch/OpenSearch*	Interroger Elasticsearch ou OpenSearch avec la syntaxe Lucene ou Query DSL	datasources:query, datasources:read	datasources:uid:datasource-uid
query_quickwit	Quickwit*	Interroger Quickwit avec la syntaxe Lucene ou Query DSL	datasources:query, datasources:read	datasources:uid:quickwit-uid
alerting_rules_read	Alerting	Lister et examiner les règles d’alerte (list, get, versions)	alert.rules.external:read, alert.rules:read, datasources:read, folders:read	folders:* ou folders:uid:alerts-folder
alerting_rules_write	Alerting	Créer, mettre à jour et supprimer des règles gérées par Grafana, ou créer explicitement des règles gérées par une source de données	alert.provisioning.provenance:write, alert.rules.external:read, alert.rules.external:write, alert.rules:create, alert.rules:delete, alert.rules:read, alert.rules:write, datasources:read, folders:read	folders:*, ou datasources:uid:<uid> pour une création externe
alerting_manage_routing	Alerting	Gérer les politiques de notification, les points de contact et les intervalles de temps	alert.notifications.external:read, alert.notifications.receivers:read, alert.notifications.routes:read, alert.notifications.time-intervals:read, alert.notifications:read, datasources:query, datasources:read, notifications.alerting.grafana.app/routingtrees:get	Portée globale
alerting_routing_write	Alerting	Créer par défaut des points de contact gérés par Grafana, ou créer explicitement des récepteurs Alertmanager externes	alert.notifications.external:read, alert.notifications.external:write, alert.notifications.receivers:create, alert.provisioning.provenance:write, datasources:read	Globale, ou datasources:uid:<uid> pour une création externe
alerting_silences_read	Alerting	Lister et examiner les silences d’alerte (list, get)	alert.instances:read, alert.silences:read	Portée globale
alerting_silences_write	Alerting	Créer, mettre à jour et expirer des silences d’alerte	alert.instances:create, alert.instances:read, alert.instances:write, alert.silences:create, alert.silences:read, alert.silences:write	Portée globale
list_oncall_schedules	OnCall	Lister les plannings de Grafana OnCall	grafana-irm-app.schedules:read, plugins.app:access	Portées spécifiques au plug-in
get_oncall_shift	OnCall	Obtenir les détails d’une astreinte OnCall spécifique	grafana-irm-app.schedules:read, plugins.app:access	Portées spécifiques au plug-in
get_current_oncall_users	OnCall	Obtenir les utilisateurs actuellement d’astreinte pour un planning spécifique	grafana-irm-app.schedules:read, grafana-irm-app.user-settings:read, plugins.app:access	Portées spécifiques au plug-in
list_oncall_teams	OnCall	Lister les équipes de Grafana OnCall	grafana-irm-app.user-settings:read, plugins.app:access	Portées spécifiques au plug-in
list_oncall_users	OnCall	Lister les utilisateurs de Grafana OnCall	grafana-irm-app.user-settings:read, plugins.app:access	Portées spécifiques au plug-in
list_alert_groups	OnCall	Lister les groupes d’alerte de Grafana OnCall avec des options de filtrage	grafana-irm-app.alert-groups:read, plugins.app:access	Portées spécifiques au plug-in
get_alert_group	OnCall	Obtenir un groupe d’alerte spécifique de Grafana OnCall à partir de son ID	grafana-irm-app.alert-groups:read, plugins.app:access	Portées spécifiques au plug-in
update_alert_group	OnCall	Accuser réception d’un groupe d’alerte, annuler l’accusé de réception, le résoudre ou annuler sa résolution	grafana-irm-app.alert-groups:read, grafana-irm-app.alert-groups:write, plugins.app:access	Portées spécifiques au plug-in
list_pyroscope_label_names	Pyroscope	Lister les noms de labels correspondant à un sélecteur	datasources:query, datasources:read	datasources:uid:pyroscope-uid
list_pyroscope_label_values	Pyroscope	Lister les valeurs de labels correspondant à un sélecteur pour un nom de label	datasources:query, datasources:read	datasources:uid:pyroscope-uid
list_pyroscope_profile_types	Pyroscope	Lister les types de profils disponibles	datasources:query, datasources:read	datasources:uid:pyroscope-uid
query_pyroscope	Pyroscope	Interroger les profils, les métriques ou les deux dans Pyroscope	datasources:query, datasources:read	datasources:uid:pyroscope-uid
get_assertions	Assertions	Obtenir le résumé des assertions pour une entité donnée	plugins.app:access	Portées spécifiques au plug-in
agento11y_manage_conversations	Observabilité des agents*	Lister, rechercher et récupérer les conversations LLM depuis Grafana Agent Observability	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access	N/A
agento11y_manage_generations	Observabilité des agents*	Récupérer les détails des générations LLM et les scores d’évaluation depuis Grafana Agent Observability	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access	N/A
agento11y_manage_agents	Observabilité des agents*	Consulter le catalogue des agents : lister les agents, obtenir la version complète d’un agent, lister l’historique des versions et les agrégats de scores par version	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access	N/A
agento11y_manage_evaluators	Observabilité des agents*	Gérer les évaluateurs, les modèles d’évaluateur et le catalogue des juges (lister, obtenir, créer ou mettre à jour, dériver, tester, supprimer)	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access ; avec les écritures activées, également grafana-agento11y-app.eval:write	N/A
agento11y_manage_eval_rules	Observabilité des agents*	Gérer les règles d’évaluation et les garde-fous (lister, obtenir, créer, mettre à jour, prévisualiser, supprimer)	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access ; avec les écritures activées, également grafana-agento11y-app.eval:write	N/A
agento11y_manage_eval_collections	Observabilité des agents*	Gérer les conversations enregistrées et les collections qui les regroupent (lister, obtenir, enregistrer, créer, mettre à jour, supprimer, ajouter et retirer des membres)	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access ; avec les écritures activées, également grafana-agento11y-app.eval:write	N/A
agento11y_manage_experiments	Observabilité des agents*	Consulter les expériences hors ligne, leurs essais, leurs scores, les métadonnées des artefacts et les facettes de filtre ; mettre à jour et annuler une expérience	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access ; avec les écritures activées, également grafana-agento11y-app.eval:write	N/A
agento11y_manage_test_suites	Observabilité des agents*	Gérer les suites de tests utilisées par les expériences hors ligne, leurs versions et leurs cas de test (lister, obtenir, créer, mettre à jour, rédiger, publier, créer ou mettre à jour, supprimer)	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access ; avec les écritures activées, également grafana-agento11y-app.eval:write	N/A
ask_assistant	Assistant*	Envoyer une invite à Grafana Assistant et renvoyer la réponse complète (plusieurs tours via contextId)	grafana-assistant-app.chats:access, plugins.app:access	Portées spécifiques au plug-in
generate_deeplink	Navigation	Générer des URL de liens profonds exactes pour les ressources Grafana	None	N/A
get_annotations	Annotations	Récupérer des annotations avec des filtres	annotations:read	annotations:* ou annotations:id:123
create_annotation	Annotations	Créer une annotation (au format standard ou Graphite)	annotations:create	annotations:*
update_annotation	Annotations	Mettre à jour des champs spécifiques d’une annotation (mise à jour partielle)	annotations:read, annotations:write	annotations:*
delete_annotation	Annotations	Supprimer une annotation par ID	annotations:delete	annotations:*
get_annotation_tags	Annotations	Lister les étiquettes d’annotation avec un filtrage facultatif	annotations:read	annotations:*
list_snapshots	Instantané	Lister les instantanés de tableaux de bord avec des filtres facultatifs de requête et de limite	snapshots:read	N/A
get_snapshot	Instantané	Obtenir les métadonnées de l’instantané et le contenu du tableau de bord à partir de la clé de l’instantané	None	N/A
create_snapshot	Instantané	Créer un instantané de tableau de bord à partir du contenu complet d’un tableau de bord	dashboards:read, snapshots:create	dashboards:uid:abc123
delete_snapshot	Instantané	Supprimer un instantané de tableau de bord par sa clé	dashboards:write, snapshots:delete	dashboards:uid:abc123
get_panel_image	Rendu	Générer une image PNG d’un tableau de bord ou panneau enregistré, d’un aperçu de provisionnement ou d’une vue Explore ponctuelle	dashboards:read, datasources:explore, datasources:query, datasources:read, provisioning.repositories:read	dashboards:uid:abc123
list_provisioning_repositories	Provisionnement	Lister les dépôts de provisionnement (par exemple, les sources git-sync) avec leur URL source, leur branche, leur état de synchronisation et leur état de santé	provisioning.grafana.app/repositories:list, provisioning.repositories:read	N/A
validate_provisioning_file	Provisioning	Effectuer un dry-run-apply d’un fichier provenant d’un dépôt de provisioning et signaler les erreurs de validation d’admission	dashboard.grafana.app/dashboards:get, dashboards:read, folder.grafana.app/folders:get, folders:read, provisioning.grafana.app/repositories:get, provisioning.repositories:read	N/A
search_docs	Docs	Rechercher dans la documentation Grafana ou lister les groupes de produits (omettre la requête pour lister les produits)	None	N/A
get_doc	Docs	Récupérer une page de documentation ; définir outline_only pour les titres, ou section pour une récupération limitée	None	N/A
search_tempo_traces	Tempo	Rechercher des traces avec TraceQL	datasources:query, datasources:read	datasources:uid:tempo-uid
query_tempo_metrics	Tempo	Calculer des métriques à partir de traces avec TraceQL	datasources:query, datasources:read	datasources:uid:tempo-uid
get_tempo_trace	Tempo	Récupérer une trace par ID	datasources:query, datasources:read	datasources:uid:tempo-uid
diff_tempo_traces	Tempo	Comparer deux traces	datasources:query, datasources:read	datasources:uid:tempo-uid
list_tempo_attribute_names	Tempo	Lister les noms des attributs de span et de ressource	datasources:query, datasources:read	datasources:uid:tempo-uid
list_tempo_attribute_values	Tempo	Lister les valeurs d’un attribut de trace	datasources:query, datasources:read	datasources:uid:tempo-uid
get_tempo_traceql_docs	Tempo	Obtenir la documentation TraceQL	None	N/A
query_graphite	Graphite*	Interroger les métriques Graphite	datasources:query, datasources:read	datasources:uid:graphite-uid
query_graphite_density	Graphite*	Interroger la densité des métriques Graphite	datasources:query, datasources:read	datasources:uid:graphite-uid
list_graphite_metrics	Graphite*	Lister les métriques Graphite	datasources:query, datasources:read	datasources:uid:graphite-uid
list_graphite_tags	Graphite*	Lister les tags Graphite	datasources:query, datasources:read	datasources:uid:graphite-uid
get_plugin	Plugins	Obtenir un plugin installé	plugins.app:access	N/A
search_plugin_information	Plugins	Rechercher dans le catalogue de plugins grafana.com	None	N/A
install_plugin	Plugins	Installer un plugin	plugins:install	N/A
grafana_api_request	API	Appeler un point de terminaison de l’API HTTP Grafana	None	Dépend du point de terminaison
* Désactivé par défaut. Ajoutez la catégorie à --enabled-tools pour l’activer.

L’outil render_grafana_app affiche des métriques et des traces dans les hôtes MCP compatibles lorsque le rendu et les catégories de requêtes correspondantes sont activés. Les outils de requête source renvoient du texte et des données structurées à des fins d’analyse. Consultez MCP Apps pour la configuration et l’intégration de bibliothèques.

Référence des options CLI

Le binaire mcp-grafana prend en charge diverses options de ligne de commande pour la configuration :

Options de transport :

• -t, --transport : type de transport (stdio, sse ou streamable-http) — valeur par défaut : stdio
• --address : hôte et port du serveur SSE/streamable-http — valeur par défaut : localhost:8000
• --base-path : chemin de base du serveur SSE/streamable-http. /healthz et /metrics sont toujours servis à la racine du serveur, et non sous ce préfixe — ce sont des points de terminaison internes réservés aux sondes et aux scrapers ; les maintenir hors du préfixe de l’application facilite l’exposition de l’API via un proxy inverse sans les exposer également
• --endpoint-path : chemin du point de terminaison du serveur streamable-http, ajouté à --base-path — valeur par défaut : /mcp
• --sse-keepalive : intervalle entre les requêtes ping envoyées à chaque client SSE, afin que les proxys inverses et les équilibreurs de charge ne ferment pas un flux d’événements inactif (ce qui met fin à la session). Définissez-le en dessous du délai d’inactivité du proxy, par exemple 30s derrière le délai par défaut de 60 s d’ingress-nginx, proxy-read-timeout. Un client est déconnecté après 3 pings consécutifs sans réponse, chacun pendant la moitié de l’intervalle. Accepte les chaînes de durée Go, minimum 1s — valeur par défaut : 0 (désactivé). S’applique uniquement à --transport sse
• --server-name : nom du serveur utilisé lors de la négociation MCP et dans OTel service.name — valeur par défaut : mcp-grafana. Remplace la variable d’environnement GRAFANA_MCP_SERVER_NAME
• --instructions-append : texte ajouté aux instructions du serveur renvoyées aux clients MCP lors de l’initialisation, afin que chaque agent connecté le voie

Lorsque --address utilise le port 0, le système d’exploitation attribue un port libre et le serveur écrit atomiquement l’adresse liée dans mcp-grafana-address dans son répertoire de travail. Le fichier est créé avec le mode 0600.

[!NOTE] Avec SSE, les en-têtes propres à chaque requête ne sont pas transmis aux appels d’outils : X-Grafana-Service-Account-Token / X-Grafana-API-Key, X-Grafana-Org-Id et les en-têtes répertoriés dans GRAFANA_FORWARD_HEADERS n’ont aucun effet ; les appels d’outils utilisent les identifiants d’environnement du serveur et les remplacements X-Grafana-URL ne fonctionnent pas. Utilisez streamable-http lorsque chaque appelant a besoin de sa propre URL Grafana, de ses propres identifiants ou de sa propre organisation.

Sécurité du transport HTTP (SSE / streamable-http uniquement) :

La validation de Host/Origin est appliquée à toutes les routes de l’écouteur MCP — /sse, /mcp et /healthz / /metrics lorsqu’ils partagent cet écouteur — afin qu’un navigateur victime d’une attaque par rebinding DNS ne puisse atteindre aucune d’entre elles. Le transport Stdio n’est pas concerné. --healthz-address et --metrics-address démarrent un écouteur distinct qui n’est pas enveloppé.

• --allowed-hosts : liste d’autorisation, séparée par des virgules, des valeurs d’en-tête Host. Par défaut, elle contient les variantes de bouclage de --address (par exemple localhost:8000,127.0.0.1:8000,[::1]:8000). Une valeur analysée comme vide (non définie, ,, ,, etc.) rétablit également les valeurs par défaut, afin qu’une faute de frappe ne puisse pas désactiver silencieusement la vérification. Les requêtes dont l’en-tête Host ne figure pas dans la liste d’autorisation sont rejetées avec 403. Passez * pour désactiver la validation de Host — uniquement si un proxy inverse de confiance valide Host. Les sondes K8s httpGet et les scrapes externes /metrics nécessiteront soit un nom d’hôte explicite dans cette liste, soit *, une sonde tcpSocket ou un port distinct (--healthz-address / --metrics-address).
• --allowed-origins : liste d’autorisation, séparée par des virgules, des valeurs d’en-tête Origin. Vide par défaut — toute requête contenant un en-tête Origin est rejetée (les navigateurs en envoient toujours un pour les requêtes inter-origines, et aucun navigateur ne devrait appeler directement ce serveur). Définissez une liste explicite pour autoriser les clients basés sur un navigateur, ou * pour désactiver la vérification.
• --allow-grafana-url-override : active la sélection de X-Grafana-URL. Utilise GRAFANA_ALLOW_URL_OVERRIDE comme valeur de repli ; désactivé par défaut. Sans liste d’autorisation, les appelants peuvent sélectionner n’importe quelle URL HTTP(S) accessible au serveur.
• --allowed-grafana-urls : liste d’autorisation facultative, séparée par des virgules, d’URL de base Grafana exactes pour les remplacements d’URL. Utilise GRAFANA_ALLOWED_URLS comme valeur de repli. Nécessite --allow-grafana-url-override ; une option explicitement vide désactive une liste héritée.

Authentification des appelants (SSE / streamable-http uniquement) :

Vous pouvez exiger que les clients MCP s’authentifient auprès du serveur. Cette authentification est distincte des identifiants utilisés par le serveur pour accéder à Grafana. Stdio n’est pas concerné.

• --server-auth-token : jeton Bearer que les appelants doivent envoyer sous la forme Authorization: Bearer <token>. Utilise la variable d’environnement MCP_GRAFANA_SERVER_TOKEN comme valeur de repli. Lorsqu’il est défini, les requêtes sans jeton valide sont rejetées avec 401 avant l’exécution de tout outil. Privilégiez la variable d’environnement afin que le secret ne soit pas visible dans les arguments du processus.

L’authentification des appelants est appliquée uniquement lorsque --server-auth-token est défini. S’il ne l’est pas et que le serveur est lié à une adresse qui n’est pas une adresse de bouclage, le serveur démarre, mais consigne une erreur de sécurité — au niveau de journalisation error, afin qu’elle ne soit pas masquée par --log-level (les adresses de bouclage et Stdio ne sont pas concernés) ; une future version majeure transformera cela en erreur au démarrage. Utilisez TLS (ou une terminaison TLS) dès que l’authentification des appelants est activée sur une adresse qui n’est pas une adresse de bouclage. Lorsque l’authentification des appelants est activée, l’en-tête Authorization validé est supprimé avant que les requêtes n’atteignent Grafana ; l’association de --server-auth-token et GRAFANA_FORWARD_HEADERS=Authorization est rejetée au démarrage.

Remplacements d’URL Grafana (streamable-http uniquement) :

[!WARNING] Les remplacements d’URL permettent aux appelants MCP de sélectionner des destinations HTTP(S) sortantes. Une liste d’autorisation limite les URL, mais n’authentifie pas les appelants et ne lie pas les jetons aux cibles.

Déployez le serveur derrière un proxy d’authentification qui autorise chaque cible, remplace les en-têtes d’URL et de jeton fournis par le client, et fournit le jeton correspondant. Limitez l’accès réseau sortant du serveur aux destinations approuvées.

Sans liste d’autorisation, un faux jeton de requête peut provoquer l’envoi de requêtes à n’importe quel service HTTP(S) accessible, y compris des services internes et de métadonnées.

Définissez GRAFANA_ALLOW_URL_OVERRIDE=true (ou --allow-grafana-url-override) pour activer la sélection sur un parc important. Pour restreindre les destinations, définissez également GRAFANA_ALLOWED_URLS=https://one.example.com,https://two.example.com/grafana (ou --allowed-grafana-urls).

Envoyez ces en-têtes avec chaque requête MCP qui sélectionne une cible :

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

Si --server-auth-token est configuré, envoyez également Authorization: Bearer <MCP caller token>. Cela authentifie l’appelant auprès du serveur MCP et est distinct de X-Grafana-Service-Account-Token, qui est destiné à l’instance Grafana sélectionnée. Votre proxy peut envoyer un jeton Grafana différent pour chaque instance ; le serveur ne partage jamais un jeton configuré entre elles. L’en-tête obsolète X-Grafana-API-Key fonctionne également. Une URL fournie dans un en-tête sans jeton Grafana de requête est rejetée. Utilisez TLS pour les requêtes entrantes, car elles transportent des jetons.

La liste d’autorisation compare les URL de base exactes, y compris le schéma, le port et le chemin ; les caractères génériques ne sont pas pris en charge. L’authentification Grafana ne protège pas contre les SSRF.

Pour une URL sélectionnée, le serveur n’utilise pas GRAFANA_SERVICE_ACCOUNT_TOKEN, GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE, GRAFANA_API_KEY, l’authentification de base de l’environnement, GRAFANA_EXTRA_HEADERS ni les certificats client. La vérification TLS reste activée même si --tls-skip-verify est défini ; un fichier d’autorité de certification configuré reste applicable. Les en-têtes explicitement transmis depuis cette requête restent applicables. Les redirections et les autres requêtes à l’API Grafana en dehors de l’URL de base sélectionnée sont bloquées. Les requêtes sans X-Grafana-URL conservent le comportement habituel de GRAFANA_URL et des identifiants d’environnement. Cette option s’applique uniquement à streamable HTTP. Elle ne fonctionne pas avec SSE, qui ne transmet pas les en-têtes propres à chaque requête aux appels d’outils ; une URL sélectionnée y est utilisée sans le jeton de l’appelant, et les appels échouent donc.

Débogage et journalisation :

• --debug : active le mode débogage pour une journalisation détaillée des requêtes/réponses HTTP
• --log-level : niveau de journalisation (debug, info, warn, error) — valeur par défaut : info

Options du client Grafana :

• --grafana-timeout : limite de temps pour les requêtes effectuées par le client Grafana. Accepte les chaînes de durée Go (par exemple 10s, 500ms) — valeur par défaut : 30s
• --allow-cross-origin-redirects : autorise les clients Grafana sortants à suivre les redirections vers un schéma, un hôte ou un port différent. Désactivé par défaut ; GRAFANA_ALLOW_CROSS_ORIGIN_REDIRECTS est la variable d’environnement de repli. L’activation de cette option peut envoyer les identifiants Grafana à la cible de redirection. Les URL Grafana sélectionnées par requête restent limitées à la cible sélectionnée.
• --include-args-in-spans : inclut les arguments des appels d’outils dans les spans OpenTelemetry. À activer uniquement dans des environnements hors production ou lorsque les arguments sont connus pour ne pas contenir de données personnelles — valeur par défaut : false

Observabilité :

• --metrics : active le point de terminaison des métriques Prometheus à /metrics
• --metrics-address : adresse distincte pour le serveur de métriques (par exemple :9090). Si elle est vide, les métriques sont servies sur le serveur principal
• --healthz-address : adresse distincte pour /healthz (par exemple :8080). Si elle est vide, /healthz est servi sur le serveur principal. Partage un écouteur avec --metrics-address lorsque les deux adresses correspondent. Les écouteurs secondaires ignorent la validation Host/Origin.
• --slow-request-threshold : consigne un événement lorsqu’une requête MCP (invocation d’outil, liste, lecture de ressource, etc.) dépasse cette durée. Accepte les chaînes de durée Go (par exemple 500ms, 5s). La valeur par défaut 0 désactive la journalisation des requêtes lentes. Consultez la section Journalisation des requêtes lentes.
• --slow-request-log-level : niveau de journalisation des événements de requêtes lentes (info ou warn) — valeur par défaut : warn.

Statistiques d’utilisation anonymes :

• --usage-stats : envoi de statistiques d’utilisation anonymes : enabled, disabled ou log (affiche sur stderr le rapport qui serait envoyé, sans rien envoyer). Remplace la variable d’environnement GRAFANA_USAGE_STATS, qui remplace à son tour DO_NOT_TRACK ; toute valeur non reconnue désactive l’envoi. Consultez la section Statistiques d’utilisation anonymes. Configuration des outils :

• --enabled-tools : Liste de catégories activées, séparées par des virgules — par défaut : toutes les catégories sauf admin, agento11y, assistant, athena, clickhouse, cloudlogging, cloudwatch, dsquery, elasticsearch, examples, graphite, quickwit, runpanelquery et snowflake. Pour activer des catégories désactivées, ajoutez-les à la liste (par exemple, "search,datasource,...,snowflake")

• --max-loki-log-limit : Nombre maximal de lignes de journal renvoyées par appel query_loki_logs — par défaut : 100. Remarque : définissez cette valeur au moins 1 en dessous de max_entries_limit_per_query côté serveur Loki afin de permettre la détection de troncature (l’outil demande en interne limit+1 pour détecter s’il existe davantage de données).

• --loki-guardrail-mode : Garde-fou de coût des requêtes Loki pour query_loki_logs — par défaut : off. Loki n’applique pas max_query_bytes_read aux requêtes de journaux sans filtre de ligne ; un sélecteur large sur une plage étendue peut donc analyser des téraoctets. Le garde-fou exige un sélecteur de flux sélectif, limite la plage temporelle effective (y compris les durées de vecteur de plage telles que [30d]) et vérifie au préalable l’estimation en octets de l’index et des statistiques de Loki avant d’exécuter la requête. shadow journalise les requêtes qui seraient bloquées, mais les laisse s’exécuter (l’aller-retour pour l’index et les statistiques a tout de même lieu) ; enforce les rejette en fournissant des indications de réécriture que le LLM peut appliquer. Sur VictoriaLogs, le garde-fou ne s’applique qu’aux requêtes de forme sélecteur ({...}) — lorsqu’aucun sélecteur n’est analysé (la forme LogsQL habituelle sans accolades), la requête passe entièrement, et la vérification du budget en octets ne s’applique jamais (aucune estimation d’index peu coûteuse). Variable d’environnement de repli : GRAFANA_LOKI_GUARDRAIL_MODE.

• --loki-guardrail-max-bytes : Nombre maximal d’octets qu’un seul appel query_loki_logs peut analyser, estimé à l’aide de l’API d’index et de statistiques de Loki — par défaut : 107374182400 (100 GiB). 0 désactive la vérification du budget en octets. Variable d’environnement de repli : GRAFANA_LOKI_GUARDRAIL_MAX_BYTES.

• --loki-guardrail-max-range : Plage temporelle effective maximale pour un seul appel query_loki_logs, y compris les durées de vecteur de plage — par défaut : 24h. Accepte les chaînes de durée Go. 0 désactive la vérification de plage. Variable d’environnement de repli : GRAFANA_LOKI_GUARDRAIL_MAX_RANGE.

• --prometheus-guardrail-mode : Garde-fou des requêtes Prometheus pour query_prometheus, query_prometheus_histogram et les requêtes Prometheus de run_panel_query — par défaut : off. Avant que la requête n’atteigne la source de données, le garde-fou limite sa plage temporelle effective ainsi que le nombre de points demandés par série. Une politique de sélecteur indépendante et activée explicitement peut exiger une contrainte d’étiquette positive non vide, en plus du nom de métrique, dans chaque sélecteur de vecteur ; consultez la politique de sélecteur pour des exemples et des limites. shadow journalise les requêtes qui seraient bloquées, mais les laisse s’exécuter ; enforce les rejette en fournissant des indications de réécriture que le LLM peut appliquer (run_panel_query le signale dans l’entrée errors du résultat pour ce panneau). Variable d’environnement de repli : GRAFANA_PROMETHEUS_GUARDRAIL_MODE.

• --prometheus-guardrail-require-selective-labels : Exiger que chaque sélecteur de vecteur inclue une contrainte d’étiquette positive non vide, en plus du nom de métrique. Par défaut : false ; indépendant des budgets de plage et de points, y compris lorsque les deux sont 0. S’applique uniquement lorsque le mode du garde-fou n’est pas off. Variable d’environnement de repli : GRAFANA_PROMETHEUS_GUARDRAIL_REQUIRE_SELECTIVE_LABELS. Les valeurs CLI explicites, y compris false, remplacent l’environnement.

• --prometheus-guardrail-max-range : Plage temporelle effective maximale pour une seule requête PromQL — par défaut : 192h. La plage effective correspond à la plage temporelle propre à la requête (zéro pour les requêtes instantanées), à laquelle s’ajoute la fenêtre la plus longue de vecteur de plage ou de sous-requête dans l’expression ; les plages de sous-requêtes imbriquées s’additionnent, de sorte que max_over_time(rate(x[5m])[30d:1m]) correspond à 30d5m. Accepte les chaînes de durée Go : écrivez donc 192h, et non 8d. 0 désactive la vérification de plage. Variable d’environnement de repli : GRAFANA_PROMETHEUS_GUARDRAIL_MAX_RANGE.

• --prometheus-guardrail-max-points : Nombre maximal de points par série qu’une requête de plage peut demander, floor(range / step) + 1 — par défaut : 11000, la limite par série propre à Prometheus. Les indications nomment le plus petit stepSeconds qui convient. 0 désactive la vérification du nombre de points. Variable d’environnement de repli : GRAFANA_PROMETHEUS_GUARDRAIL_MAX_POINTS.

• --prometheus-guardrail-max-metric-cardinality : Politique de portée TSDB activée explicitement. Par défaut : 0 (désactivée). Un nom de métrique exact dont le nombre de séries dépasse le seuil indiqué exige un sélecteur exact non vide sur une étiquette de portée configurée. Active uniquement lorsque le mode n’est pas off. Variable d’environnement de repli : GRAFANA_PROMETHEUS_GUARDRAIL_MAX_METRIC_CARDINALITY.

• --prometheus-guardrail-cardinality-cache-ttl : Durée de vie des instantanés TSDB mis en cache. Par défaut : 10m ; 0 utilise également 10m. Variable d’environnement de repli : GRAFANA_PROMETHEUS_GUARDRAIL_CARDINALITY_CACHE_TTL.

• --prometheus-guardrail-cardinality-scope-labels : Étiquettes séparées par des virgules dont les sélecteurs exacts non vides satisfont la politique de cardinalité. Par défaut : job,instance,namespace,pod,service,cluster ; une valeur vide utilise ces valeurs par défaut. __name__ n’est pas autorisé. Variable d’environnement de repli : GRAFANA_PROMETHEUS_GUARDRAIL_CARDINALITY_SCOPE_LABELS. Les paramètres CLI explicites remplacent les variables d’environnement correspondantes.

  Limites du garde-fou Prometheus : la vérification des points établit un budget pour la résolution demandée, et non pour le nombre de séries, d’échantillons ou d’évaluations de sous-requêtes ; Grafana peut aligner la plage ou élargir le pas. Les modificateurs offset et @ sont ignorés. Les macros Grafana telles que $__rate_interval et $__range sont remplacées avant la mesure de l’expression, avec les valeurs utilisées par Grafana ($__rate_interval vaut quatre fois le pas). Les expressions que le garde-fou ne peut toujours pas analyser (par exemple celles contenant des variables de tableau de bord telles que $window, ou une syntaxe acceptée uniquement par un autre dialecte) sont vérifiées uniquement en fonction de la plage temporelle et du pas propres à la requête, puis exécutées. run_panel_query ne possède pas de paramètre de pas ; il élargit donc son pas d’une minute pour les longues plages afin de rester sous 11000 points, comme le fait Grafana, ou sous une valeur --prometheus-guardrail-max-points inférieure en mode enforce.

• --prometheus-enforced-matchers : Sélecteurs d’étiquettes PromQL ajoutés par ET à chaque requête Prometheus native afin de limiter les séries accessibles (par exemple, environment=~"prod|staging"). Nécessite --disable-api. Consultez Application des règles aux requêtes Prometheus.

• --loki-enforced-matchers : Sélecteurs d’étiquettes LogQL ajoutés par ET à chaque requête Loki native afin de limiter les flux de journaux accessibles (par exemple, environment=~"prod|staging"). Nécessite --disable-api. Consultez Application des règles aux requêtes Loki.

• --loki-label-enumeration-fallback : Comportement des outils d’énumération des étiquettes lorsque les sélecteurs négatifs imposés ne peuvent pas les limiter : reject (par défaut) ou unfiltered. Consultez Application des règles aux requêtes Loki.

• --dashboard-schema : Définissez sur v2 pour que update_dashboard rejette un corps classique v1 (panels[]) qui créerait un nouveau tableau de bord lorsque Grafana utilise le schéma de tableau de bord v2 ; l’erreur contient un corps v2 minimal à réutiliser. Les tableaux de bord v1 existants restent modifiables, et les instances Grafana sans v2 ne sont pas affectées. Par défaut : vide (aucun changement). Variable d’environnement de repli : GRAFANA_DASHBOARD_SCHEMA.

• --disable-search : Désactiver les outils de recherche

• --disable-datasource : Désactiver les outils de source de données

• --disable-incident : Désactiver les outils d’incident

• --disable-prometheus : Désactiver les outils Prometheus

• --disable-write : Désactiver les outils d’écriture (opérations de création/mise à jour)

• --disable-query : Désactiver les outils de requête (outils qui exécutent une requête sur une source de données) ; les outils de métadonnées et de découverte restent disponibles

• --enable-query : Garder les outils de requête SQL brute (query_sql, query_influxdb) enregistrés même avec --disable-write, et garder query_datasource, une source de render_grafana_app, disponible. Pour les outils SQL bruts, cela équivaut à --enable-write-tools=query_sql,query_influxdb ; conservé comme raccourci pour ce cas courant.

• --enable-write-tools : Liste de noms d’outils individuels, séparés par des virgules, à garder enregistrés même avec --disable-write, pour les outils dont le comportement d’écriture est suffisamment ciblé pour être réactivé indépendamment. N’a aucun effet sur un outil dont toute la catégorie est désactivée. Par exemple, --enable-write-tools=generate_deeplink permet de continuer à raccourcir les URL (shorten=true) avec --disable-write, et --enable-write-tools=alerting_rules_write autorise les modifications des règles d’alerte sans activer les autres outils d’écriture.

• --disable-loki : Désactiver les outils Loki

• --disable-elasticsearch : Désactiver les outils Elasticsearch et OpenSearch

• --disable-quickwit : Désactiver les outils Quickwit

• --disable-influxdb : Désactiver les outils InfluxDB

• --disable-alerting : Désactiver les outils d’alerte

• --disable-dashboard : Désactiver les outils de tableau de bord

• --disable-oncall : Désactiver les outils OnCall

• --disable-asserts : Désactiver les outils asserts

• --disable-admin : Désactiver les outils d’administration

• --disable-pyroscope : Désactiver les outils Pyroscope

• --disable-navigation : Désactiver les outils de navigation

• --disable-rendering : Désactiver les outils de rendu (export d’images de panneaux/tableaux de bord)

• --disable-snapshot : Désactiver les outils d’instantané

• --disable-cloudwatch : Désactiver les outils CloudWatch

• --disable-cloudlogging : Désactiver les outils Google Cloud Logging

• --disable-examples : Désactiver les outils d’exemples de requêtes

• --disable-sql : Désactiver les outils de source de données SQL (ClickHouse, Snowflake, Athena, MySQL, PostgreSQL, MSSQL, BigQuery). Les alias --disable-clickhouse, --disable-snowflake, --disable-athena fonctionnent également.

• --disable-runpanelquery : Désactiver les outils d’exécution de requêtes de panneau

• --disable-graphite : Désactiver les outils Graphite

• --disable-dsquery : Désactiver la source query_datasource de render_grafana_app

• --disable-provisioning : Désactiver les outils de provisionnement

• --disable-agento11y : Désactiver les outils Agent Observability

• --disable-assistant : Désactiver les outils Grafana Assistant

• --disable-docs : Désactiver les outils de documentation

Mode lecture seule

L’option --disable-write permet d’exécuter le serveur MCP en mode lecture seule, empêchant toute opération d’écriture sur votre instance Grafana. Ce mode est utile dans les situations où vous souhaitez fournir un accès sécurisé en lecture seule, par exemple :

• Utiliser des comptes de service disposant d’autorisations limitées à la lecture
• Fournir aux assistants IA des données d’observabilité sans leur permettre de les modifier
• Exécuter le serveur dans des environnements de production où l’accès en écriture doit être restreint
• Effectuer des tests et du développement en empêchant les modifications accidentelles

Lorsque --disable-write est activé, les opérations d’écriture suivantes sont désactivées :

Outils de tableau de bord :

• update_dashboard

Outils de dossier :

• create_folder

Outils d’incident :

• create_incident
• add_activity_to_incident
• update_incident

Outils d’alerte :

• alerting_rules_write (opérations de création, de mise à jour et de suppression)
• alerting_silences_write (opérations de création, de mise à jour et de suppression)
• alerting_routing_write (opération create_contact_point)

Chaque outil d’écriture d’alerte peut être conservé individuellement avec --enable-write-tools=<name>.

Outils OnCall :

• update_alert_group

Outils d’annotation :

• create_annotation
• update_annotation
• delete_annotation

Outils d’instantané :

• create_snapshot
• delete_snapshot

Outils de navigation :

• generate_deeplink (shorten=true est ignoré et l’URL complète est renvoyée ; transmettez --enable-write-tools=generate_deeplink pour conserver le raccourcissement des URL)

Outils de requête SQL brute :

Ces outils exécutent toute requête que vous leur fournissez sans l’inspecter ; ils peuvent donc effectuer des écritures si les identifiants de la source de données le permettent — query_sql exécutera un DROP TABLE, et query_influxdb exécutera un DELETE. Le mode lecture seule les supprime donc. Transmettez --enable-query pour les conserver lorsque vous savez que les identifiants de la source de données sont en lecture seule.

• query_sql
• query_influxdb

Outils Agent Observability :

• agento11y_manage_evaluators (opérations upsert, delete, fork et test evaluator)
• agento11y_manage_eval_rules (opérations de création, de mise à jour et de suppression de règles et de garde-fous, ainsi que de prévisualisation)
• agento11y_manage_eval_collections (enregistrement et suppression de conversations sauvegardées ; création, mise à jour et suppression de collections ; ajout et retrait de membres des collections)
• agento11y_manage_experiments (opérations de mise à jour et d’annulation d’expériences)
• agento11y_manage_test_suites (création et mise à jour de suites de tests ; création et publication de versions ; opérations upsert et delete sur les cas de test)

Toutes les opérations de lecture restent disponibles : vous pouvez interroger les tableaux de bord, exécuter des requêtes PromQL/LogQL, répertorier les ressources et récupérer des données. Les langages de requête qui ne permettent pas d’effectuer des écritures — PromQL, LogQL, TraceQL, le DSL Elasticsearch, Graphite et CloudWatch — conservent leurs outils de requête en mode lecture seule ; seuls les outils SQL bruts répertoriés ci-dessus sont supprimés.

Mode sans requête

Le drapeau --disable-query supprime tous les outils qui exécutent une requête sur une source de données, tout en conservant les outils de métadonnées et de découverte. Cette option est utile si vous souhaitez qu’un assistant puisse explorer les éléments disponibles — sources de données, tableaux de bord, noms de métriques, libellés, schémas de tables — sans exécuter de requêtes potentiellement coûteuses ou susceptibles de révéler des données, par exemple lorsque le compte de service dispose de datasources:read, mais pas de datasources:query.

C’est le plus strict des trois paramètres de requête et il prévaut sur --enable-query :

Drapeaux	Outils de requête sécurisés (query_prometheus, query_loki_logs, run_panel_query, …)	Outils de requête SQL brutes (query_sql, query_influxdb)
(aucun)	enregistrés	enregistrés
--disable-write	enregistrés	non enregistrés
--disable-write --enable-query	enregistrés	enregistrés
--disable-query	non enregistrés	non enregistrés
--disable-query --enable-query	non enregistrés	non enregistrés

Lorsque --disable-query est activé, les outils suivants ne sont pas enregistrés :

Outils Prometheus :

• query_prometheus
• query_prometheus_histogram

Outils de rendu :

• render_grafana_app

Outils Loki :

• query_loki_logs
• query_loki_patterns

query_loki_stats et analyze_loki_labels restent enregistrés : tous deux envoient un sélecteur à la source de données, mais lisent l’index et renvoient le nombre de flux, de blocs et d’octets plutôt que le contenu des journaux.

Outils Elasticsearch/OpenSearch et Quickwit :

• query_elasticsearch
• query_quickwit

Outils InfluxDB (également supprimés par --disable-write, voir ci-dessus)** :**

• query_influxdb

Outils de sources de données SQL (également supprimés par --disable-write, voir ci-dessus)** :**

• query_sql

Outils Graphite :

• query_graphite
• query_graphite_density

Outils CloudWatch :

• query_cloudwatch
• query_cloudwatch_logs

Outils Google Cloud Logging :

• query_cloud_logging

Outils Pyroscope :

• query_pyroscope

Outils d’exécution de requêtes de panneau :

• run_panel_query

Les catégories elasticsearch, quickwit, influxdb et runpanelquery ne contiennent rien d’autre ; elles n’enregistrent donc aucun outil lorsque les requêtes sont désactivées. Les outils associés de toutes les autres catégories — list_prometheus_metric_names, list_loki_label_values, describe_sql_table, list_cloudwatch_metrics, list_cloud_logging_projects, etc. — restent disponibles.

Notez que --disable-query contrôle les outils de requête et le chemin POST vers grafana_api_request-/api/ds/query, mais ne contrôle pas toutes les routes vers une source de données. En mode lecture seule, grafana_api_request autorise les requêtes POST vers /api/ds/query uniquement lorsque les outils de requête sont activés (même contrôle que pour les outils SQL bruts — bloqué par --disable-write, sauf si --enable-query le remplace). get_panel_image, qui effectue le rendu d’un panneau côté serveur, n’est pas concerné.

Configuration TLS du client (pour les connexions Grafana) :

• --tls-cert-file : chemin du fichier de certificat TLS pour l’authentification du client
• --tls-key-file : chemin du fichier de clé privée TLS pour l’authentification du client
• --tls-ca-file : chemin du fichier de certificat d’autorité de certification TLS pour la vérification du serveur
• --tls-skip-verify : ignorer la vérification du certificat TLS (non sécurisé)

Configuration TLS du serveur (transport streamable-http uniquement) :

• --server.tls-cert-file : chemin du fichier de certificat TLS pour HTTPS côté serveur
• --server.tls-key-file : chemin du fichier de clé privée TLS pour HTTPS côté serveur

Utilisation

Ce serveur MCP fonctionne avec les instances Grafana locales et Grafana Cloud. Pour Grafana Cloud, utilisez l’URL de votre instance (par exemple, https://myinstance.grafana.net) au lieu de http://localhost:3000 dans les exemples de configuration ci-dessous.

1. Si vous utilisez l’authentification par jeton de compte de service, créez dans Grafana un compte de service disposant des autorisations nécessaires pour utiliser les outils souhaités, générez un jeton de compte de service et copiez-le dans le presse-papiers pour l’utiliser dans le fichier de configuration. Consultez la documentation Grafana sur les comptes de service pour savoir comment créer des jetons de compte de service. Conseil : si vous n’êtes pas à l’aise avec la configuration de portées RBAC précises, vous pouvez choisir une option plus simple (mais moins restrictive) : attribuer au compte de service le rôle intégré Editor. Celui-ci accorde de larges droits de lecture et d’écriture couvrant la plupart des opérations du serveur MCP. Utilisez-le si la simplicité prime sur le principe du moindre privilège.

   Remarque : la variable d’environnement GRAFANA_API_KEY est obsolète et sera supprimée dans une prochaine version. Veuillez utiliser GRAFANA_SERVICE_ACCOUNT_TOKEN à la place. L’ancien nom de variable restera pris en charge pour assurer la rétrocompatibilité, mais des avertissements d’obsolescence seront affichés.

Lire le jeton de compte de service depuis un fichier

Au lieu de transmettre le jeton directement avec GRAFANA_SERVICE_ACCOUNT_TOKEN, vous pouvez définir GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE sur le chemin d’un fichier contenant le jeton. Le fichier est relu à chaque requête ; les jetons renouvelés sont donc pris en compte automatiquement, sans redémarrer le serveur.

Cette méthode est particulièrement utile dans Kubernetes, où un Secret monté en tant que volume est mis à jour sur place lorsque le Secret sous-jacent change (généralement en moins d’une minute). Associé au cache client par requête — indexé sur la valeur du jeton —, un jeton renouvelé entraîne de manière transparente la création d’un nouveau client, sans redémarrage du pod ni interruption de service :

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

Les espaces blancs autour du contenu du fichier (y compris le saut de ligne final) sont supprimés. Si GRAFANA_SERVICE_ACCOUNT_TOKEN et GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE sont tous deux définis, le jeton transmis directement est prioritaire.

Prise en charge de plusieurs organisations

Vous pouvez indiquer l’organisation avec laquelle interagir de l’une des façons suivantes :

• Variable d’environnement : définissez GRAFANA_ORG_ID sur l’identifiant numérique de l’organisation
• En-tête HTTP : définissez X-Grafana-Org-Id avec le transport HTTP streamable (l’en-tête est prioritaire sur la variable d’environnement, ce qui permet également de définir une organisation par défaut).

Lorsqu’un identifiant d’organisation est fourni, le serveur MCP ajoute l’en-tête X-Grafana-Org-Id à toutes les requêtes envoyées à Grafana, afin que les opérations soient effectuées dans le contexte de l’organisation spécifiée.

Sélection dynamique de l’organisation (par appel)

Les options ci-dessus fixent l’organisation pour toute la connexion. Pour permettre à une même connexion de cibler différentes organisations à chaque appel d’outil, démarrez le serveur avec le drapeau --dynamic-multi-org. Cette option est désactivée par défaut.

Lorsqu’elle est activée, chaque outil accepte un argument facultatif orgId qui remplace, pour cet appel, l’organisation de la connexion (ce qui détermine à la fois l’en-tête X-Grafana-Org-Id et, pour les API de la plateforme d’applications, l’espace de noms Kubernetes résolu). Les outils de source de données proxy sont également découverts dans toutes les organisations auxquelles les identifiants donnent accès. Les appels qui omettent orgId utilisent l’organisation par défaut de la connexion.

Cette fonctionnalité ne fonctionne qu’avec des identifiants associés à plusieurs organisations (par exemple, un utilisateur ou une identité agissant au nom d’un utilisateur) ; un jeton de compte de service reste lié à une seule organisation. Utilisez l’outil user_info pour découvrir les valeurs orgId valides.

Exemple avec un identifiant d’organisation :

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

En-têtes HTTP personnalisés

Vous pouvez ajouter des en-têtes HTTP arbitraires à toutes les requêtes de l’API Grafana à l’aide de la variable d’environnement GRAFANA_EXTRA_HEADERS. Sa valeur doit être un objet JSON associant les noms d’en-tête à leurs valeurs.

Exemple avec des en-têtes personnalisés :

{
  "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\"}"
      }
    }
  }
}

Proxy SOCKS5

Vous pouvez acheminer toutes les requêtes que ce serveur envoie à Grafana via un proxy SOCKS5 à l’aide de la variable d’environnement GRAFANA_SOCKS5_PROXY. Le proxy s’applique au trafic Grafana de ce serveur uniquement : il ne modifie pas les variables globales HTTP_PROXY/HTTPS_PROXY et, lorsqu’il est défini, il remplace leur sélection de proxy uniquement pour les transports Grafana, sans affecter les autres serveurs MCP ni votre session shell. S’il n’est pas défini, le comportement reste inchangé.

L’URL doit utiliser le schéma socks5:// ou socks5h:// (Go les traite de manière identique : la résolution du nom d’hôte est déléguée au proxy) et peut inclure des identifiants, par exemple socks5://user:pass@127.0.0.1:1080.

Exemple :

{
  "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"
      }
    }
  }
}

Une URL de proxy non valide provoque une erreur au démarrage. Si la création d’une connexion via le proxy échoue à l’exécution, le serveur échoue de manière sécurisée au lieu d’envoyer silencieusement le trafic Grafana directement.

Transmettre les en-têtes du client (transport Streamable-HTTP uniquement)

Lorsque le serveur MCP s’exécute derrière une passerelle ou un proxy inverse qui gère le SSO (par exemple, un AWS ALB avec OIDC), le cookie de session de chaque utilisateur doit parvenir à Grafana afin que celui-ci puisse associer la requête à l’utilisateur authentifié. La variable d’environnement GRAFANA_FORWARD_HEADERS active cette fonctionnalité en définissant une liste d’autorisation, séparée par des virgules, des noms d’en-tête à copier de la requête HTTP entrante vers chaque requête de l’API Grafana sortante.

Cette fonctionnalité s’applique uniquement au transport streamable-http (-t streamable-http). Elle n’a aucun effet en mode stdio ou SSE.

Exemple : transmettre le cookie de session

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

Vous pouvez transmettre plusieurs en-têtes en les séparant par des virgules :

GRAFANA_FORWARD_HEADERS=Cookie,X-Session-Id

Les en-têtes transmis sont fusionnés avec ceux définis dans GRAFANA_EXTRA_HEADERS. Si un nom d’en-tête apparaît dans les deux, la valeur de la requête entrante est prioritaire pour cette requête.

Les en-têtes de contexte de trace (traceparent, tracestate, baggage) font exception : le serveur propage lui-même le contexte de trace, de sorte qu’une valeur transmise ne remplace jamais celle qu’il injecte. Consultez la page observabilité.

2. Plusieurs options s’offrent à vous pour installer mcp-grafana :

   • uvx (recommandé) : si uv est installé, aucune configuration supplémentaire n’est nécessaire — uvx téléchargera et exécutera automatiquement le serveur :

     uvx mcp-grafana
     

   • Image Docker : utilisez l’image Docker précompilée disponible sur Docker Hub.

     Important : le point d’entrée de l’image Docker est configuré pour exécuter le serveur MCP en mode SSE par défaut, mais la plupart des utilisateurs préféreront le mode STDIO pour une intégration directe avec des assistants IA comme Claude Desktop :

     1. Mode STDIO : en mode stdio, vous devez remplacer explicitement la valeur par défaut avec -t stdio et inclure le drapeau -i pour garder stdin ouvert :

     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
     

     Remarque — sécurisez les modes réseau : en modes SSE et streamable-http, le conteneur se lie à une adresse qui n’est pas une adresse de bouclage (0.0.0.0:8000). Sans jeton d’appelant, le serveur démarre, mais consigne une erreur de sécurité (au niveau de journalisation error, afin qu’elle ne soit pas masquée par --log-level ; il refusera de démarrer dans une prochaine version majeure). Définissez MCP_GRAFANA_SERVER_TOKEN pour exiger un Authorization: Bearer <token> des clients (recommandé). Le mode STDIO n’est pas concerné. Consultez la page Authentification des appelants.

     2. Mode SSE : dans ce mode, le serveur s’exécute comme un serveur HTTP auquel les clients se connectent. Vous devez exposer le port 8000 à l’aide du drapeau -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
     

     3. Mode HTTP streamable : dans ce mode, le serveur fonctionne comme un processus indépendant capable de gérer plusieurs connexions client. Vous devez exposer le port 8000 à l’aide du drapeau -p. Pour ce mode, vous devez remplacer explicitement la valeur par défaut avec -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
     

     Pour le mode HTTP streamable avec HTTPS et des certificats TLS côté serveur :

     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
     

   • Télécharger le binaire : téléchargez la dernière version de mcp-grafana depuis la page des versions et placez-la dans votre $PATH.

   • Compiler à partir des sources : si vous disposez d’une chaîne d’outils Go, vous pouvez également compiler et installer le serveur à partir des sources, en utilisant la variable d’environnement GOBIN pour indiquer le répertoire où installer le binaire. Ce répertoire doit également se trouver dans votre $PATH.

     GOBIN="$HOME/go/bin" go install github.com/grafana/mcp-grafana/v2/cmd/mcp-grafana@latest
     

   • Déployer sur Kubernetes avec Helm : utilisez le chart Helm du dépôt helm-charts de 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
     

3. Ajoutez la configuration du serveur au fichier de configuration de votre client. Par exemple, pour Claude Desktop :

   Avec uvx :

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

   Avec le binaire :

   {
     "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"
         }
       }
     }
   }
   

Remarque : si Error: spawn mcp-grafana ENOENT s’affiche dans Claude Desktop, vous devez indiquer le chemin complet vers mcp-grafana.

Avec 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"
      }
    }
  }
}

Remarque : l’argument -t stdio est essentiel ici, car il remplace le mode SSE par défaut de l’image Docker.

Utiliser VSCode avec un serveur MCP distant

Si vous utilisez VSCode et exécutez le serveur MCP en mode SSE (mode par défaut lorsque vous utilisez l’image Docker sans remplacer le transport), veillez à ce que votre .vscode/settings.json inclue les éléments suivants :

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

Pour le mode HTTPS streamable HTTP avec des certificats TLS côté serveur :

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

Mode débogage

Vous pouvez activer le mode débogage pour le transport Grafana en ajoutant l’option -debug à la commande. Cela fournit des journaux détaillés des requêtes et réponses HTTP entre le serveur MCP et l’API Grafana, ce qui peut être utile pour le dépannage.

Pour utiliser le mode débogage avec la configuration de Claude Desktop, mettez à jour votre configuration comme suit :

Si vous utilisez le binaire :

{
  "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>"
      }
    }
  }
}

Si vous utilisez 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>"
      }
    }
  }
}

Remarque : comme pour la configuration standard, l’argument -t stdio est nécessaire pour remplacer le mode SSE par défaut de l’image Docker.

Configuration TLS

Si votre instance Grafana se trouve derrière un mTLS ou nécessite des certificats TLS personnalisés, vous pouvez configurer le serveur MCP pour utiliser des certificats personnalisés. Le serveur prend en charge les options de configuration TLS suivantes :

• --tls-cert-file : chemin d’accès au fichier de certificat TLS pour l’authentification du client
• --tls-key-file : chemin d’accès au fichier de clé privée TLS pour l’authentification du client
• --tls-ca-file : chemin d’accès au fichier de certificat d’autorité de certification TLS pour la vérification du serveur
• --tls-skip-verify : ignorer la vérification du certificat TLS (non sécurisé, à utiliser uniquement pour les tests)

Exemple avec authentification par certificat client :

{
  "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>"
      }
    }
  }
}

Exemple avec 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>"
      }
    }
  }
}

La configuration TLS s’applique à tous les clients HTTP utilisés par le serveur MCP, notamment :

• Le client OpenAPI principal de Grafana
• Les clients de source de données Prometheus
• Les clients de source de données Loki
• Les clients de gestion des incidents
• Les clients d’alerting
• Les clients Asserts

Exemples d’utilisation directe de la CLI :

Pour tester avec des certificats auto-signés :

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

Avec authentification par certificat client :

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

Avec un certificat d’autorité de certification personnalisé uniquement :

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

Utilisation programmatique :

Si vous utilisez cette bibliothèque de manière programmatique, vous pouvez également créer des fonctions de contexte compatibles 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)

Validation des URL :

Lorsque vous appelez directement NewGrafanaClient (stdio ou construction programmatique), validez les URL au préalable pour éviter un panic atteignable :

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

Configuration TLS du serveur (transport streamable HTTP uniquement)

Lorsque vous utilisez le transport streamable HTTP (-t streamable-http), vous pouvez configurer le serveur MCP pour qu’il serve du HTTPS plutôt que du HTTP. Cela est utile lorsque vous devez sécuriser la connexion entre votre client MCP et le serveur lui-même.

Le serveur prend en charge les options de configuration TLS suivantes pour le transport streamable HTTP :

• --server.tls-cert-file : chemin d’accès au fichier de certificat TLS pour le HTTPS du serveur (obligatoire pour TLS)
• --server.tls-key-file : chemin d’accès au fichier de clé privée TLS pour le HTTPS du serveur (obligatoire pour TLS)

Remarque : ces options sont entièrement distinctes des options TLS client documentées ci-dessus. Les options TLS client configurent la connexion du serveur MCP à Grafana, tandis que ces options TLS serveur configurent la connexion des clients au serveur MCP lors de l’utilisation du transport streamable HTTP.

Exemple avec un serveur HTTPS streamable HTTP :

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

Le serveur MCP démarrerait ainsi sur le port HTTPS 8443. Les clients se connecteraient alors à https://localhost:8443/ au lieu de http://localhost:8000/.

Exemple Docker avec TLS côté serveur :

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

Point de terminaison de vérification de l’état

Lors de l’utilisation des transports SSE (-t sse) ou streamable HTTP (-t streamable-http), le serveur MCP expose un point de terminaison de vérification de l’état à l’adresse /healthz. Les équilibreurs de charge, les systèmes de surveillance ou les plateformes d’orchestration peuvent utiliser ce point de terminaison pour vérifier que le serveur fonctionne et accepte les connexions.

Point de terminaison : GET /healthz

Réponse :

• Code d’état : 200 OK
• Corps : ok

Exemple d’utilisation :

# 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

Remarque : le point de terminaison de vérification de l’état est disponible uniquement avec les transports SSE ou streamable HTTP. Il n’est pas disponible avec le transport stdio (-t stdio), car stdio n’expose pas de serveur HTTP.

Statistiques d’utilisation anonymes

Le serveur peut transmettre à Grafana Labs des statistiques anonymes sur son utilisation : les outils appelés, le nombre d’appels ayant échoué et la configuration du serveur. Chaque rapport couvre un processus serveur — et non un utilisateur ou une conversation — et est envoyé toutes les 4 h, ainsi qu’une fois à l’arrêt. La transmission est activée par défaut. Pour la désactiver, définissez --usage-stats=disabled, GRAFANA_USAGE_STATS=disabled ou DO_NOT_TRACK=1.

Les arguments des outils, les noms des ressources, les requêtes, les lignes de journal, les messages d’erreur et les identifiants ne sont jamais transmis. Les options sont enregistrées uniquement par leur nom, jamais par leur valeur, et l’instance Grafana est décrite uniquement comme cloud ou self_hosted — jamais par son URL, son nom d’hôte, son identifiant de stack ou son organisation. Aucune donnée n’est associée à un utilisateur, une session ou un client : aucun identifiant de session n’est transmis et il est impossible d’attribuer un appel d’outil à un client particulier.

# 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 désactive également la transmission, conformément à la convention inter-outils DO_NOT_TRACK. Seul 1 a un effet, il ne peut que désactiver la transmission, et --usage-stats comme GRAFANA_USAGE_STATS l’emportent sur lui ; un hôte qui le définit globalement peut donc toujours réactiver la transmission pour un serveur donné.

GRAFANA_USAGE_STATS_ENDPOINT modifie la destination. Il ne désactive pas la transmission.

Pour consulter la liste complète des champs, savoir ce qui n’est jamais transmis, comprendre comment lire les données et connaître leurs limites, voir Statistiques d’utilisation anonymes.

Observabilité

Le serveur MCP prend en charge les métriques Prometheus, le traçage distribué OpenTelemetry et l’exportation des journaux OpenTelemetry, conformément aux conventions sémantiques OTel MCP. Le traçage et l’exportation des journaux sont configurés au moyen des variables d’environnement standard OTEL_* et fonctionnent avec tous les transports.

Remarque : mcp-grafana ne prend actuellement en charge que le transport OTLP/gRPC pour les traces et les journaux. OTEL_EXPORTER_OTLP_PROTOCOL (et ses variantes _TRACES_PROTOCOL / _LOGS_PROTOCOL) ne sont pas prises en compte — gRPC est utilisé dans tous les cas.

Métriques

Avec les transports SSE ou streamable HTTP, activez les métriques Prometheus à l’aide de l’option --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

Métriques disponibles :

Métrique	Type	Description
mcp_server_operation_duration_seconds	Histogramme	Durée des opérations MCP (étiquettes : mcp_method_name, gen_ai_tool_name, error_type, network_transport, mcp_protocol_version)
http_server_request_duration_seconds	Histogramme	Durée des requêtes du serveur HTTP (depuis otelhttp)

Remarque : les métriques sont disponibles uniquement avec les transports SSE ou streamable HTTP. Elles ne sont pas disponibles avec le transport stdio.

Lorsque le garde-fou de coût Loki (--loki-guardrail-mode) est activé, quatre compteurs supplémentaires enregistrent ses décisions :

Métrique	Type	Description
mcp_loki_guardrail_admitted_total	Compteur	Requêtes ayant satisfait tous les contrôles activés (étiquettes : backend)
mcp_loki_guardrail_would_block_total	Compteur	Requêtes ayant échoué à un contrôle en mode shadow et exécutées malgré tout (étiquettes : backend, reason)
mcp_loki_guardrail_blocked_total	Compteur	Requêtes rejetées en mode enforce (étiquettes : backend, reason)
mcp_loki_guardrail_fail_open_total	Compteur	Requêtes que le garde-fou n’a pas pu évaluer et qu’il a admises (étiquettes : backend, cause)

reason correspond à l’une des valeurs selector, range, bytes ; cause correspond à l’une des valeurs unparseable, estimate_failed ; backend correspond à l’une des valeurs loki, victorialogs, unknown. Une requête qui déclenche plusieurs contrôles est comptabilisée une seule fois, avec l’étiquette du premier contrôle exécuté (selector, puis range, puis bytes), de sorte que les quatre compteurs couvrent l’ensemble des requêtes soumises au garde-fou sans chevauchement. Voir Observabilité pour savoir comment les interpréter lors d’un déploiement progressif de shadow vers enforce.

Lorsque le garde-fou Prometheus (--prometheus-guardrail-mode) est activé, quatre compteurs enregistrent ses décisions de la même manière :

Métrique	Type	Description
mcp_prometheus_guardrail_admitted_total	Compteur	Requêtes ayant satisfait tous les contrôles activés
mcp_prometheus_guardrail_would_block_total	Compteur	Requêtes ayant échoué à un contrôle en mode shadow et exécutées malgré tout (étiquettes : reason)
mcp_prometheus_guardrail_blocked_total	Compteur	Requêtes rejetées en mode enforce (étiquettes : reason)
mcp_prometheus_guardrail_fail_open_total	Compteur	Requêtes admises alors qu’une évaluation activée était indisponible (étiquettes : reason)

reason correspond à selector, range, points ou cardinality sur would_block et blocked, et est comptabilisé une seule fois sous le premier contrôle ayant échoué dans cet ordre. fail_open utilise unparseable ou cardinality_unknown. La politique de cardinalité facultative utilise des statistiques TSDB mises en cache sur les N valeurs les plus fréquentes pour exiger un périmètre explicite sur les métriques connues pour leur cardinalité élevée ; elle n’estime pas les séries sélectionnées et ne prouve pas que les métriques manquantes sont sans risque. Les points de terminaison TSDB non pris en charge entraînent une autorisation par défaut pour cette politique. Il n’existe pas d’étiquette backend.

Les intégrateurs de bibliothèques doivent définir GrafanaConfig.MeterProvider (l’équivalent métrique de GrafanaConfig.Logger) : le garde-fou s’exécute dans un gestionnaire d’outil et ne dispose donc d’aucune option de constructeur ; un processus qui installe un MeterProvider global sans opération supprimerait autrement tous les enregistrements.

Journalisation des requêtes lentes

L’option --slow-request-threshold émet un événement de journal structuré chaque fois qu’une requête MCP (invocation d’outil, liste, lecture de ressource, etc.) dépasse la durée indiquée. Elle est utile pour diagnostiquer les requêtes et appels d’outils lents sans être submergé par l’intégralité du journal de débogage.

# 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

L’événement de journal contient les attributs structurés suivants :

Attribut	Description
mcp.method	Méthode MCP (par exemple, tools/call, tools/list, resources/read)
duration	Durée observée de la requête
threshold	Seuil configuré
tool	Nom de l’outil (présent uniquement pour les méthodes tools/call)
error	Valeur de l’erreur, si la requête a échoué (contexte fourni au mieux ; le contenu dépend de l’enrobage des erreurs en amont)
error.type	Classification des erreurs à cardinalité limitée (_OTHER pour les erreurs non typées)

La journalisation des requêtes lentes fonctionne avec tous les transports (y compris stdio) et ne nécessite pas --metrics. Le seuil par défaut de 0 la désactive entièrement. Les outils relayés passent par tools/call et sont automatiquement pris en compte.

Traçage

Le traçage distribué est configuré au moyen des variables d’environnement standard OTEL_* et fonctionne indépendamment de l’option --metrics. Lorsque OTEL_EXPORTER_OTLP_ENDPOINT (ou la variable spécifique au signal OTEL_EXPORTER_OTLP_TRACES_ENDPOINT) est défini, le serveur exporte les traces via 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

Les spans d’appel d’outil suivent la convention de nommage semconv (tools/call <tool_name>) et incluent des attributs tels que gen_ai.tool.name, mcp.method.name et mcp.session.id. Le serveur prend également en charge la propagation du contexte de trace W3C depuis le champ _meta des requêtes d’appel d’outil.

Journaux

Lorsque OTEL_EXPORTER_OTLP_ENDPOINT (ou la variable spécifique au signal OTEL_EXPORTER_OTLP_LOGS_ENDPOINT) est défini, le serveur exporte également des journaux structurés via OTLP/gRPC, en plus de la sortie texte brut existante sur stderr. Le pont otelslog associe automatiquement trace_id et span_id au span actif, afin que les enregistrements de journal soient corrélés aux traces déjà émises par le serveur. Les traces et les journaux résolvent leurs points de terminaison indépendamment, ce qui permet d’activer les deux signaux séparément : définir uniquement OTEL_EXPORTER_OTLP_TRACES_ENDPOINT active le traçage sans exporter les journaux, définir uniquement OTEL_EXPORTER_OTLP_LOGS_ENDPOINT active l’exportation des journaux sans traçage, et définir la variable générique OTEL_EXPORTER_OTLP_ENDPOINT active les deux.

Si vous utilisez la variable générique OTEL_EXPORTER_OTLP_ENDPOINT mais souhaitez désactiver l’exportation des journaux (par exemple, si votre backend ne prend pas en charge LogsService), définissez :

OTEL_LOGS_EXPORTER=none

Cela empêche le serveur de créer un exportateur de journaux OTLP, quelle que soit la configuration du point de terminaison, et évite ainsi des erreurs telles que unknown service opentelemetry.proto.collector.logs.v1.LogsService.

La journalisation sur stderr reste inchangée lorsque la journalisation OTLP est activée ; vous pouvez continuer à vous fier aux journaux du conteneur ou rediriger stderr vers /dev/null si vous préférez.

# 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

Le transport est OTLP/gRPC (port par défaut 4317). Les journaux peuvent être envoyés directement à n’importe quel backend géré acceptant OTLP/gRPC — par exemple, Grafana Cloud — en définissant OTEL_EXPORTER_OTLP_LOGS_ENDPOINT (ou la variable générique OTEL_EXPORTER_OTLP_ENDPOINT) sur le point de terminaison gRPC distant et en fournissant les informations d’authentification via OTEL_EXPORTER_OTLP_LOGS_HEADERS (ou OTEL_EXPORTER_OTLP_HEADERS), comme dans l’exemple de traçage ci-dessus. Un collecteur OTel local est facultatif : il est utile pour la diffusion vers plusieurs destinations, le traitement par lots ou le routage vers plusieurs backends, mais n’est pas nécessaire.

Les variantes propres aux signaux 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 et OTEL_EXPORTER_OTLP_LOGS_COMPRESSION sont prises en compte et remplacent leurs équivalents génériques OTEL_EXPORTER_OTLP_* — consultez la spécification de l’exportateur OTel pour obtenir la liste complète et connaître les règles de priorité.

Si le collecteur configuré est inaccessible, les enregistrements de journaux sont mis en mémoire tampon (file d’attente par défaut : 2048) et les plus anciens sont supprimés lorsque la file est pleine. Le processus continue sans bloquer le service. Configurez un collecteur OTel local si vous avez besoin d’une mise en mémoire tampon sans perte pendant les interruptions.

Les journaux sont également exportés avec le transport stdio, ce qui facilite la centralisation des journaux des instances locales mcp-grafana appelées par des clients IDE.

Exemple Docker avec métriques, traces et journaux :

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

Application des règles aux requêtes Prometheus

--prometheus-enforced-matchers permet à un opérateur de restreindre les séries Prometheus que les outils Prometheus natifs peuvent lire, en ajoutant par un ET logique un ensemble fixe de sélecteurs d’étiquettes PromQL à chaque sélecteur de vecteur de chaque requête Prometheus native émise par le serveur. Cette fonctionnalité est utile lorsqu’une source de données contient des séries qui ne doivent pas être exposées (par exemple, des métriques comportant des étiquettes de locataire ou de client sensibles), mais que vous ne pouvez pas restreindre l’accès au niveau de Prometheus.

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

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

Fonctionnement :

• Les sélecteurs sont analysés une seule fois au démarrage (une entrée invalide interrompt le démarrage du serveur), puis ajoutés à chaque sélecteur de vecteur de chaque requête. Une requête utilisateur ne peut que réduire les résultats dans les limites imposées — elle ne peut jamais les élargir.
• Cela concerne query_prometheus, query_prometheus_histogram et les panneaux Prometheus dans run_panel_query.
• La découverte native de Prometheus via list_prometheus_label_names, list_prometheus_label_values et list_prometheus_metric_names applique également les sélecteurs à chaque sélecteur de série, y compris lorsqu’aucun sélecteur n’est fourni.
• list_prometheus_metric_metadata est refusé lorsque l’application des règles est activée : le point de terminaison de métadonnées de Prometheus ne peut pas filtrer par étiquettes de série et fusionne les métadonnées de plusieurs cibles. La découverte de Cloud Monitoring est également refusée, car ses API de découverte ne peuvent pas appliquer l’ensemble complet des règles de sélecteurs Prometheus.
• Le système refuse par défaut : toute requête qui ne peut pas être analysée est rejetée au lieu d’être envoyée sans filtre.

[!IMPORTANT] D’autres outils activés peuvent contourner ces sélecteurs. Désactivez grafana_api_request avec --disable-api, les outils de rendu avec --disable-rendering et Grafana Assistant avec --disable-assistant (ou --disable-write). En particulier, render_grafana_app peut envoyer des requêtes Prometheus sans filtre via sa source query_datasource. --disable-dsquery ferme cette source, mais ne désactive pas le rendu des panneaux côté serveur. Les instantanés de tableaux de bord existants peuvent également contenir des données sans restriction ; utilisez --disable-snapshot si cela pose problème.

Application des règles aux requêtes Loki

--loki-enforced-matchers permet à un opérateur de restreindre les flux de journaux Loki que le serveur peut lire, en ajoutant par un ET logique un ensemble fixe de sélecteurs d’étiquettes LogQL à chaque requête Loki native émise par le serveur. Cette fonctionnalité est utile lorsqu’une source de données contient des flux qui ne doivent pas être exposés (par exemple, des journaux susceptibles de contenir des informations sensibles), mais que vous ne pouvez pas restreindre l’accès au niveau de Grafana ou de Loki (OSS ne propose aucun contrôle d’accès aux étiquettes par source de données ou par utilisateur).

# 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

Fonctionnement :

• Les sélecteurs sont analysés une seule fois au démarrage (une entrée invalide interrompt le démarrage du serveur), puis ajoutés à chaque sélecteur de flux de chaque requête. Comme Loki combine les sélecteurs par un ET au sein d’un sélecteur, une requête utilisateur ne peut que réduire les résultats dans les limites imposées — elle ne peut jamais les élargir. Un sélecteur utilisateur qui entre en conflit avec la règle (par exemple, qui demande {namespace="vault"} alors qu’une exclusion s’applique) ne renvoie simplement aucun résultat.
• Cela concerne query_loki_logs, query_loki_stats, query_loki_patterns, list_loki_label_names et list_loki_label_values.
• Le système refuse par défaut : toute requête qui ne peut pas être analysée est rejetée au lieu d’être envoyée sans filtre.
• Les sources de données VictoriaLogs utilisent LogsQL, qui ne peut pas être réécrit de manière sûre ; elles sont donc entièrement refusées lorsque l’application des règles est activée.
• Les sélecteurs uniquement négatifs ne peuvent pas restreindre les points de terminaison d’énumération des étiquettes (Loki rejette un sélecteur autonome sans sélecteur positif). Gérez ce cas particulier avec --loki-label-enumeration-fallback (reject par défaut, ou unfiltered pour autoriser l’énumération sans restriction des métadonnées des étiquettes — les lignes de journal ne sont jamais exposées). Les sélecteurs positifs/de liste d’autorisation ne sont pas concernés.

[!IMPORTANT] L’application des règles ne concerne que les outils de requête Loki. D’autres outils peuvent accéder aux données des journaux Loki par des chemins qui ne passent jamais par le backend soumis aux règles ; pour que la restriction soit réellement appliquée, vous devez également les désactiver :

• --disable-api — grafana_api_request peut interroger directement le proxy de la source de données Loki (contournement complet).
• --disable-rendering — get_panel_image effectue le rendu des panneaux Loki côté serveur et produit des images contenant des lignes de journal sans restriction.
• --disable-assistant — ask_assistant délègue à Grafana Assistant, qui lit côté serveur tous les flux Loki. Cet outil n’est enregistré que lorsque les outils d’écriture sont activés ; --disable-write le désactive donc également.

Au démarrage, le serveur consigne un avertissement indiquant lesquels de ces outils sont encore activés. run_panel_query est sûr (il réutilise le chemin de requête soumis aux règles). Les outils Tempo interrogent les traces, et non les journaux Loki ; ils ne constituent donc pas un contournement. Les instantanés de tableaux de bord (--disable-snapshot) peuvent également intégrer des données de panneaux de journaux capturées en dehors du mécanisme d’application des règles.

Dépannage

Compatibilité des versions de Grafana

Si vous rencontrez l’erreur suivante lors de l’utilisation d’outils liés aux sources de données :

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

Cela indique généralement que vous utilisez une version de Grafana antérieure à 9.0. Le point de terminaison d’API /datasources/uid/{uid} a été introduit dans Grafana 9.0 ; les opérations sur les sources de données échoueront avec les versions antérieures.

Solution : mettez à niveau votre instance Grafana vers la version 9.0 ou ultérieure pour résoudre ce problème.

Développement

Les contributions sont les bienvenues ! Veuillez d’abord lire CONTRIBUTING.md : ce document explique ce qui a sa place dans ce serveur et comment proposer des modifications.

Si vous ajoutez un nouvel outil, veuillez soumettre une proposition d’outil avant d’écrire le code. Chaque outil activé par défaut est envoyé au modèle à chaque requête de chaque utilisateur ; nous préférons donc discuter de l’idée plutôt que de refuser une demande de fusion déjà terminée. Les corrections de bogues, la documentation, les tests et les nouveaux paramètres pour les outils existants ne nécessitent pas de proposition : envoyez simplement une demande de fusion.

Ce projet est écrit en Go. Les versions des outils et les tâches de développement se trouvent dans mise.toml : installez mise, exécutez mise install pour obtenir les versions épinglées des outils, puis mise tasks pour afficher les tâches.

Pour exécuter le serveur localement en mode STDIO (mode par défaut pour le développement local), utilisez :

mise run run

Pour exécuter le serveur localement en mode SSE, utilisez :

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

Vous pouvez également exécuter le serveur avec le transport SSE dans une image Docker personnalisée. Comme l’image Docker publiée, le point d’entrée de cette image personnalisée utilise le mode SSE par défaut. Pour créer l’image, utilisez :

mise run build-image

Et pour exécuter l’image en mode SSE (mode par défaut), utilisez :

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

Si vous devez plutôt l’exécuter en mode STDIO, remplacez le paramètre de transport :

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

Tests

Trois types de tests sont disponibles :

1. Tests unitaires (aucune dépendance externe requise) :

mise run test-unit

Vous pouvez également exécuter les tests unitaires avec :

mise run test

2. Tests d’intégration (des conteneurs Docker doivent être en cours d’exécution) :

mise run test-integration

3. Tests Cloud (une instance Grafana Cloud et des identifiants sont requis) :

mise run test-cloud

Remarque : les tests Cloud sont configurés automatiquement dans CI. Pour le développement local, vous devez configurer votre propre instance Grafana Cloud et obtenir des identifiants.

Des tests d’intégration plus complets nécessitent qu’une instance Grafana soit exécutée localement sur le port 3000 ; vous pouvez en démarrer une avec Docker Compose :

docker-compose up -d

Si vous ajoutez d’autres outils, veuillez ajouter des tests d’intégration correspondants. Les tests existants constituent un bon point de départ.

Analyse statique

Pour analyser le code, exécutez :

mise run lint

Cela inclut un linter personnalisé qui détecte les virgules non échappées dans les balises de struct jsonschema. Les virgules dans les champs description doivent être échappées avec \\, pour éviter une troncature silencieuse. Vous pouvez exécuter uniquement ce linter avec :

mise run lint-jsonschema

Consultez la documentation du linter JSONSchema pour plus de détails.

Licence

Ce projet est distribué sous la licence Apache, version 2.0.