Grafana

Implements the Model Context Protocol (MCP) server specification using the mark3labs/mcp-go framework, translating standardized MCP tool invocations into native Grafana REST API calls. The server exposes 20+ tool categories through a unified MCP interface, handling request/response marshaling, error translation, and protocol-level session management across stdio, SSE, and HTTP transports.

Supports three distinct transport modes configured at startup: stdio for direct process integration with local clients, Server-Sent Events (SSE) for unidirectional streaming over HTTP, and streamable-HTTP for bidirectional communication. Each transport is implemented as a separate handler in cmd/mcp-grafana/main.go with transport-agnostic tool execution logic, enabling the same server binary to serve different deployment architectures without modification.

Exposes Prometheus metrics from mcp-grafana itself, tracking tool invocation counts, execution latencies, error rates, and API call performance. Implements a /metrics endpoint (Prometheus format) that exports metrics like tool_invocations_total, tool_execution_duration_seconds, grafana_api_calls_total, and datasource_query_errors. Enables operators to monitor mcp-grafana's health and performance through Grafana dashboards, alerting on high error rates or slow tool execution.

Implements automatic tool discovery that generates MCP tool schemas dynamically based on Grafana's API capabilities and configured datasources. The tool management framework introspects Grafana's /api/datasources, /api/v1/rules, and other endpoints to determine available tools, then generates MCP-compliant tool schemas with typed parameters, descriptions, and validation rules. Clients discover available tools via MCP's ListTools mechanism, receiving only tools applicable to their session's Grafana instance and permissions.

Manages Grafana authentication through API keys provided per session, enforcing role-based access control (RBAC) inherited from Grafana's permission model. Validates API keys against Grafana's /api/auth/identity endpoint, caches authentication state per session, and enforces Grafana's datasource and dashboard permissions on all tool invocations. Supports multiple authentication methods (API keys, OAuth tokens) and propagates Grafana's RBAC decisions to MCP tool execution, ensuring users can only query resources they have permission to access.

Supports TLS encryption for HTTP and SSE transports through configurable certificate and key files. Implements standard Go TLS server configuration with support for custom CA certificates, client certificate validation, and TLS version pinning. Enables secure communication between MCP clients and mcp-grafana server, protecting API keys and query results in transit. Configuration is provided via environment variables or command-line flags at server startup.

Implements context window awareness for LLM interactions by tracking token usage across tool invocations and providing token budgeting information to clients. Monitors query result sizes and estimates token consumption based on response content, enabling AI assistants to make informed decisions about query scope and result pagination. Provides token usage metrics through OpenTelemetry spans and Prometheus metrics, allowing operators to track and optimize token consumption.

Supports read-only deployment mode that disables all write operations and restricts tool invocations to query-only capabilities. Implements permission checks that prevent dashboard modifications, alert rule changes, and incident updates, exposing only tools for querying dashboards, datasources, alerts, and logs. Configuration is enforced at the tool execution layer, ensuring read-only semantics are maintained across all transport modes and authentication contexts.

Integrates Grafana Sift (AI-powered log analysis) and Asserts (SLO and error tracking) through dedicated MCP tools that expose their REST APIs. Implements tools for Sift pattern detection, anomaly analysis, and log summarization, as well as Asserts SLO tracking, error rate analysis, and service health assessment. Enables AI assistants to leverage Grafana's advanced analytics capabilities for root cause analysis and service reliability insights.

Dedicated tool set for Pyroscope profiling data querying that handles profile selection by service/app, time range filtering, and flame graph data retrieval. Implements tools for querying CPU profiles, memory profiles, and goroutine profiles with support for profile comparison and diff analysis. Enables AI assistants to investigate performance issues by querying profiling data, identifying hot functions, and correlating profile changes with system events.

Exposes Grafana dashboard discovery through MCP tools that query the Grafana API's /api/search endpoint with support for filtering by tags, folder, starred status, and query strings. Returns structured dashboard metadata including UID, title, folder path, tags, and permissions, enabling AI assistants to locate relevant dashboards for incident investigation or metric exploration without manual navigation.

Provides unified query execution across Grafana's supported datasources (Prometheus, Loki, Pyroscope, Elasticsearch, InfluxDB, etc.) through datasource-specific tool implementations. Each datasource type has dedicated tools that translate MCP query parameters into native query languages (PromQL, LogQL, etc.), execute via Grafana's /api/datasources/proxy endpoint, and return typed results. The tool management framework automatically discovers available datasources and exposes only compatible query tools based on datasource type.

Dedicated tool set for Prometheus querying that handles PromQL syntax, range vector operations, and time-series aggregation. Implements tools for instant queries (single point-in-time metric values), range queries (time-series data over intervals), and metric metadata retrieval (available metrics, labels, label values). Supports Prometheus-specific features like rate() calculations, aggregations, and histogram quantiles through pass-through PromQL execution.

Dedicated tool set for Loki log querying that handles LogQL syntax, label-based stream selection, and log filtering. Implements tools for log range queries (logs over time intervals), instant log queries, and label/stream metadata retrieval. Supports Loki-specific features like pattern matching, metric extraction from logs, and label value enumeration for dynamic query construction.

Exposes Grafana's alerting system through tools that discover alert rules, retrieve their current state, and query alert history. Implements tools for listing alerts by status (firing, resolved, pending), retrieving alert rule definitions with conditions and notification channels, and querying alert state changes over time. Integrates with Grafana's unified alerting backend (/api/v1/rules endpoint) to provide real-time alert status and historical state transitions.

Exposes Grafana OnCall incident management capabilities through MCP tools that retrieve active incidents, incident details, escalation policies, and on-call schedules. Implements tools for querying incident state, retrieving incident timelines with event history, and accessing on-call rotation information. Integrates with Grafana OnCall's REST API to provide incident context during investigation and enable AI assistants to understand incident severity, assigned responders, and escalation status.

Implements per-session configuration management through a SessionManager that maintains isolated context for each MCP client connection. Each session stores Grafana instance URL, API key, organization ID, and user preferences, enabling multiple users or clients to connect to different Grafana instances or organizations through a single mcp-grafana server instance. Session context is passed through the MCP tool execution chain, ensuring all queries execute against the correct Grafana instance and organization without cross-contamination.

Integrates OpenTelemetry tracing throughout mcp-grafana's execution path, instrumenting MCP tool invocations, Grafana API calls, and datasource queries with distributed traces. Exports traces to OpenTelemetry-compatible backends (Jaeger, Tempo, etc.) configured via environment variables. Provides visibility into tool execution latency, API call performance, and error propagation, enabling operators to debug performance issues and monitor mcp-grafana's own observability.