Configure the Grafana MCP server on Grafana Labs

Authentication

Fri, 25 Sep 2026 09:18:01 +0000

Authentication

The Grafana MCP server needs credentials to call the Grafana API. Use a service account token (recommended) or a username and password.

What you’ll achieve

You set the environment variables (or equivalent) so the server can authenticate to your Grafana instance. The same credentials apply whether you run the server with uvx, Docker, a binary, or Helm.

Before you begin

A Grafana instance (Grafana 9.0 or later).
For token auth: a service account with a token and the RBAC permissions needed for the tools you use.

Use a service account token

Set GRAFANA_URL and GRAFANA_SERVICE_ACCOUNT_TOKEN in the environment passed to the server.

GRAFANA_URL: Your Grafana base URL (for example, http://localhost:3000 or https://myinstance.grafana.net).
GRAFANA_SERVICE_ACCOUNT_TOKEN: The token you created for the service account.

The deprecated GRAFANA_API_KEY is still supported but will be removed in a future version; use GRAFANA_SERVICE_ACCOUNT_TOKEN instead.

Read the token from a file

Set GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE to a file path that contains the token instead of passing the value inline. The file is read fresh on every request, so a rotated token is picked up automatically without restarting the server.

This is useful in Kubernetes, where a Secret mounted as a volume is updated in place when the underlying Secret changes. Because the server’s client cache is keyed on the token value, a rotated token transparently produces a new client with no pod restart:

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

Surrounding whitespace (including a trailing newline) is trimmed from the file contents. If both GRAFANA_SERVICE_ACCOUNT_TOKEN and GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE are set, the inline token takes precedence.

For HTTP deployments that select a Grafana URL per request, each request must supply a token for its selected instance. The server does not reuse GRAFANA_SERVICE_ACCOUNT_TOKEN or the token file for that request.

Use username and password

You can use basic auth by setting GRAFANA_USERNAME and GRAFANA_PASSWORD instead of a token. This is less suitable for automation; prefer a service account token when possible.

Next steps

Enable and disable tools to control which MCP tools are available.
Transports and addresses for stdio, SSE, and streamable-http.

Transports and addresses

Thu, 01 Oct 2026 13:22:11 +0000

Transports and addresses

The Grafana MCP server supports three transports: stdio (default for local use), SSE, and streamable-http. Choose the one that matches how your MCP client connects.

What you’ll achieve

You run the server with the right transport and, for SSE or streamable-http, the correct address and path so your client can connect.

Before you begin

The server installed (for example, Install with uvx or Install with Docker).

Use stdio transport

With stdio (the default when you run the binary or uvx), the server talks to the client over standard input and output. Use this when the client launches the server as a subprocess (for example, Claude Desktop, Cursor). No --address or port is needed.

mcp-grafana
# or
uvx mcp-grafana

Use SSE or streamable-http transport

With -t sse or -t streamable-http, the server listens on an address (default localhost:8000). Use --address to change host and port, and optionally --base-path or --endpoint-path for path configuration.

mcp-grafana -t sse
mcp-grafana -t streamable-http --address :9090

Clients connect to the server URL (for example, http://localhost:8000/sse for SSE). For streamable-http, the default endpoint path is /mcp (override with --endpoint-path if your client expects a different path).

--base-path prefixes the application routes on the listener:

mcp-grafana -t sse --address :8000 --base-path /my-base --metrics

serves /my-base/sse. /healthz and /metrics are internal-only endpoints for probes and scrapers, so they always stay at the server root — never under --base-path — regardless of this flag.

Note
Over SSE, per-request headers do not reach tool calls: X-Grafana-Service-Account-Token / X-Grafana-API-Key, X-Grafana-Org-Id, and headers listed in GRAFANA_FORWARD_HEADERS have no effect, tool calls use the server’s environment credentials, and X-Grafana-URL overrides do not work. Use streamable-http when each caller needs its own Grafana URL, credentials, or organization.

Next steps

Server TLS (streamable-http) if you need HTTPS for the MCP server.
Client TLS if Grafana is behind mTLS or custom certificates.

Enable and disable tools

Mon, 19 Oct 2026 10:16:42 +0000

Enable and disable tools

You can limit which tools the server exposes (to reduce context window use or lock down capabilities) and run the server in read-only mode.

What you’ll achieve

You enable only the tool categories you need, or disable write operations globally with --disable-write.

Before you begin

The server installed and configured (Set up and Authentication).

Enable optional tool categories

Some tool categories are disabled by default:

runpanelquery – Run dashboard panel queries.
examples – Query examples for datasource types.
sql – SQL datasource tools (ClickHouse, Snowflake, Athena, MySQL, PostgreSQL, MSSQL). Back-compat aliases clickhouse, snowflake, athena also work.
cloudwatch – CloudWatch tools.
cloudlogging – Google Cloud Logging tools (requires the googlecloud-logging-datasource plugin, version 1.8.0 or later).
elasticsearch – Elasticsearch query tool.
quickwit – Quickwit query tool.
influxdb – InfluxDB query tool (Flux and InfluxQL).
agento11y – Agent Observability tools for LLM conversations, generations, evaluation scores, agents, evaluators, eval rules, guards, saved conversations, collections, offline experiments, and the test suites those experiments run against.
assistant – Grafana Assistant tool (ask_assistant); requires the Grafana Assistant plugin and is write-gated.
admin – Admin tools (teams, users, roles, permissions).

--enabled-tools replaces the default list, so to add an optional category you must pass the full set. For example, to keep the defaults and also enable runpanelquery and examples:

mcp-grafana --enabled-tools search,datasource,incident,prometheus,loki,alerting,dashboard,folder,oncall,asserts,pyroscope,navigation,tempo,annotations,rendering,snapshot,runpanelquery,examples

Refer to Command-line flags for the default list.

Disable tool categories

Use --disable-<category> to turn off a whole category (for example, --disable-oncall, --disable-alerting, --disable-dashboard). For every flag, read-only behavior, and TLS-related flags, refer to Command-line flags.

Tempo tools can be disabled with --disable-tempo or removed from --enabled-tools. They also respect --disable-query.

Run in read-only mode

Use --disable-write to disable all write operations. The server can still read dashboards, run queries, and list resources, but it cannot create or update dashboards, incidents, alert groups, alert rules, annotations, snapshots, or Agent Observability evaluators, eval rules, guards, saved conversations, and collections.

Read-only mode also removes query_sql and query_influxdb: they pass the query to the datasource unfiltered, so they can write whenever the datasource credentials permit it. Add --enable-query to keep them when those credentials are known to be read-only.

In read-only mode, generate_deeplink ignores shorten=true and returns the full URL, because Grafana creates short URLs through a POST request. Add --enable-write-tools=generate_deeplink to keep URL shortening without re-enabling any other write tool.

Run without query execution

Use --disable-query to remove every tool that executes a query against a datasource, such as query_prometheus, query_loki_logs, query_sql, and run_panel_query. The server can still list datasources and dashboards, explore metric names, labels, and table schemas, and generate deeplinks, but it can’t run the queries themselves.

--disable-query is the strongest of the three query settings: it wins over --enable-query, and it removes the query tools that --disable-write leaves in place. Refer to Command-line flags for the full list of affected tools.

Next steps

Introduction for an overview of tools and RBAC.
Configure authentication if you have not set credentials yet.

Client TLS (Grafana connection)

Wed, 29 Jul 2026 17:47:59 +0200

Client TLS (Grafana connection)

If your Grafana instance uses mTLS or a custom CA, configure the MCP server to use the correct certificates when it calls the Grafana API.

What you’ll achieve

The server uses your client certificate and key (and optionally a CA file) for HTTPS requests to Grafana, or verifies Grafana’s server certificate with a custom CA.

Before you begin

Client certificate and key (and CA file if needed) for your Grafana endpoint.
The server installed (binary or Docker with access to the cert files).

Configure client TLS

Use these flags when starting the server:

–tls-cert-file – Path to the client certificate file.
–tls-key-file – Path to the client private key file.
–tls-ca-file – Path to the CA certificate file for server verification.
–tls-skip-verify – Skip TLS verification (insecure; use only for testing).

Example:

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

With Docker, mount the cert directory and pass the paths inside the container (for example, /certs/client.crt).

Next steps

Client configuration examples for full MCP JSON (binary and Docker) with TLS flags.
Server TLS (streamable-http) if you want HTTPS for the MCP server itself.
Authentication for Grafana credentials.
Command-line flags for all TLS-related flags.

Server TLS (streamable-http)

Wed, 29 Jul 2026 17:47:59 +0200

Server TLS (streamable-http)

When you use the streamable-http transport, you can serve the MCP server over HTTPS using your own TLS certificate and key.

What you’ll achieve

Clients connect to the server with https:// instead of http://. This is separate from client TLS, which configures how the server connects to Grafana.

Before you begin

A TLS certificate and private key for the host and port where the server will listen.
The server run with -t streamable-http.

Configure server TLS

Use these flags with streamable-http:

–server.tls-cert-file – Path to the server TLS certificate file.
–server.tls-key-file – Path to the server TLS private key file.

Example:

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

Clients then connect to https://localhost:8443 with the streamable-http path (default --endpoint-path is /mcp, for example https://localhost:8443/mcp).

Next steps

Transports and addresses for transport options.
Client TLS (Grafana connection) for TLS toward Grafana.

Multi-organization and headers

Thu, 01 Oct 2026 13:22:11 +0000

Multi-organization and headers

You can point the server at a specific Grafana organization and add custom HTTP headers to every request to Grafana.

What you’ll achieve

All Grafana API calls use the chosen organization context, and any extra headers you need (for example, tenant or custom auth) are sent automatically.

Before you begin

A Grafana instance with multiple organizations (or a need for custom headers).
The server configured with Authentication.

Set the organization

Set GRAFANA_ORG_ID to the numeric organization ID. The server sends X-Grafana-Org-Id on all requests to Grafana.

When using streamable-http, you can also send X-Grafana-Org-Id from the client; the header takes precedence over the environment variable so you can override the default org per request.

Select an organization per tool call

The settings above fix the organization for the whole connection. To let a single connection target different organizations per call, start the server with the --dynamic-multi-org flag. This is off by default.

When enabled:

Every tool accepts an optional orgId argument that overrides the connection’s organization for that call, setting both the X-Grafana-Org-Id header and, for app-platform APIs, the resolved Kubernetes namespace. Calls that omit orgId use the connection’s default organization.
Tempo tools resolve the datasource in the calling organization, so you can target a Tempo datasource in any org with orgId plus its datasourceUid.

This only works for credentials that belong to more than one organization (for example a user or on-behalf-of identity); a service-account token stays bound to its single organization. Call the user_info tool to discover which orgId values are valid.

Send custom headers

Set GRAFANA_EXTRA_HEADERS to a JSON object mapping header names to values. These headers are added to every Grafana API request.

Example:

"GRAFANA_EXTRA_HEADERS": "{\"X-Custom-Header\": \"value\", \"X-Tenant-ID\": \"tenant-123\"}"

Next steps

Authentication for Grafana credentials.
Enable and disable tools to limit which tools are available.

Command-line flags

Mon, 19 Oct 2026 10:16:42 +0000

Command-line flags

The mcp-grafana binary accepts flags for transports, tools, TLS, and observability. Run mcp-grafana --help for the exact list in your installed build.

What you’ll achieve

You can look up defaults, choose --disable-* flags, or configure TLS without reading the source.

Before you begin

You need a way to run mcp-grafana on your machine—for example, a release binary, uvx, or a container.

Configure transport and HTTP options

-t / --transport: Transport type (stdio, sse, or streamable-http). Default: stdio.
--address: Host and port for the SSE or streamable-http server. Default: localhost:8000.
--base-path: Base path for the SSE or streamable-http server. With --base-path /my-base, SSE is at /my-base/sse and streamable-http at /my-base/mcp. /healthz and /metrics are internal-only endpoints for probes and scrapers and always stay at the server root, never under this prefix.
--endpoint-path: HTTP path for the streamable-http MCP endpoint, appended to --base-path. Default: /mcp.
--instructions-append: Text appended to the server instructions returned to MCP clients on initialize, so every connecting agent sees it.

Configure HTTP transport security

The SSE and streamable-http transports validate Host and Origin headers on every route on the MCP listener (/sse, /mcp, and /healthz / /metrics when they stay on that listener) to block DNS-rebinding attacks. Stdio transport is unaffected. Side listeners started by --healthz-address or --metrics-address are not wrapped.

--allowed-hosts: Comma-separated allowlist of Host header values. When unset (or when the parsed value is empty — for example, ,,,), it falls back to loopback variants of --address (for example, localhost:8000, 127.0.0.1:8000, [::1]:8000). Pass * to disable Host validation — only safe when a trusted reverse proxy validates Host.
--allowed-origins: Comma-separated allowlist of Origin header values. Empty by default — any request that carries an Origin header is rejected (browsers always send Origin for cross-origin requests, and no browser should be calling this server directly). Pass an explicit list to permit browser clients, or * to disable the check.

When deploying behind an ingress or reverse proxy that forwards the original Host, set --allowed-hosts to the expected hostname (for example, --allowed-hosts mcp.example.com). Kubernetes httpGet liveness/readiness probes send Host: <pod-ip>:<port> by default — either set --allowed-hosts '*', override the probe’s host: field, use a tcpSocket probe, or bind /healthz on --healthz-address (and /metrics on --metrics-address). Those side listeners are not wrapped by Host/Origin validation.

Configure caller authentication

The SSE and streamable-http transports can authenticate the caller (the MCP client connecting to mcp-grafana). This is separate from the credentials the server uses to reach Grafana: it controls who may invoke the server, so an unauthenticated client can’t borrow the server’s Grafana identity or run tools. Stdio is a local pipe and is never affected.

--server-auth-token: Bearer token that callers must present in the Authorization: Bearer <token> header. Falls back to the MCP_GRAFANA_SERVER_TOKEN environment variable. When set, requests without a valid token are rejected with 401 before any tool runs. Prefer the environment variable over the flag so the secret doesn’t appear in the process argument list.

Bind policy

Caller authentication is enforced only when --server-auth-token is set. When it isn’t, the network transports warn (but still start) on an externally reachable address:

Transport / bind	Behavior
`stdio`	No caller authentication (local pipe).
SSE / streamable-http on a loopback address (`localhost`, `127.0.0.1`, `::1`)	Caller token optional.
SSE / streamable-http on any other address	Starts and logs a security error (at the `error` log level, so it isn’t suppressed by `--log-level`) unless `--server-auth-token` is set.

Note
The permissive default preserves backward compatibility for existing deployments (such as the container’s 0.0.0.0 bind). A future major release will make an unauthenticated non-loopback bind a startup error. Set --server-auth-token now to require caller authentication and prepare for that change.

Bearer authentication only protects the token in transit if the connection is encrypted. Terminate TLS in front of the server, or use server TLS for streamable-http, whenever you set --server-auth-token on a non-loopback address.

When caller authentication is enabled, the Authorization header is reserved for the caller token and is stripped after validation, so it is never forwarded to Grafana. Setting --server-auth-token together with GRAFANA_FORWARD_HEADERS=Authorization is contradictory and the server refuses to start; remove Authorization from GRAFANA_FORWARD_HEADERS, or unset the caller token to run in proxy-forwarding mode.

Select a Grafana URL per request

Warning
URL overrides let MCP callers select outbound HTTP(S) destinations. An allowlist limits URLs but does not authenticate callers, bind tokens to targets, or enforce network egress policy.

Deploy behind an authenticating proxy that authorizes each caller’s target, removes client-supplied X-Grafana-URL and Grafana token headers, and supplies the approved URL with its matching token. Restrict outbound access to approved destinations with a network policy, firewall, or egress proxy. These controls matter even with an allowlist.

Without a URL allowlist, a fake request token can cause requests to any reachable HTTP(S) service, including internal and metadata services.

On the streamable-http transport, callers can select a Grafana instance for each request. This is disabled by default.

--allow-grafana-url-override: Enable selection through X-Grafana-URL. Falls back to GRAFANA_ALLOW_URL_OVERRIDE when the flag is not set.
--allowed-grafana-urls: Optional comma-separated list of exact Grafana base URLs that callers may select. Falls back to GRAFANA_ALLOWED_URLS when the flag is not set. It requires the enable switch; an explicitly empty flag clears an inherited list.

For a large fleet selected by a proxy, GRAFANA_ALLOW_URL_OVERRIDE=true enables selection without listing every instance in GRAFANA_ALLOWED_URLS. The deployment controls in the warning above still apply. The proxy must send both X-Grafana-URL: <target base URL> and X-Grafana-Service-Account-Token: <token for that target> on each MCP request. The deprecated X-Grafana-API-Key header also works. The server uses the token from that request and does not send its environment Grafana credentials to a selected target. If caller authentication is configured, the Authorization header carries the separate MCP caller token.

Without --allowed-grafana-urls, the server logs a security error at startup. Outbound Grafana requests are pinned to the selected base URL, including across redirects. Selection does not work over SSE, which does not pass per-request headers to tool calls; a selected URL there is used without the caller’s token, so the calls fail.

Configure debug and logging

--debug: Enable debug mode for detailed HTTP request and response logging to and from the Grafana API.
--log-level: Log level (debug, info, warn, error). Default: info.

Configure observability endpoints

--metrics: Expose a Prometheus metrics endpoint at /metrics (SSE and streamable-http only).
--metrics-address: Optional separate listen address for metrics (for example, :9090). If empty, metrics are served on the main HTTP server.
--healthz-address: Optional separate listen address for /healthz (for example, :8080). If empty, /healthz is served on the main HTTP server. If this matches --metrics-address, both routes share one extra listener. The side listener is not wrapped by Host/Origin validation, so Kubernetes probes can reach it while --address stays on loopback.

Configure anonymous usage statistics

--usage-stats: Anonymous usage statistics reporting: enabled, disabled, or log to print the report that would be sent to stderr and send nothing. Overrides the GRAFANA_USAGE_STATS environment variable. Default: enabled.

GRAFANA_USAGE_STATS_ENDPOINT changes where reports are sent.

Refer to Anonymous usage statistics for the full list of fields, what is never sent, and how to read the data.

Configure tool categories

--enabled-tools: Comma-separated list of enabled tool categories. The default is exactly:

search,datasource,incident,prometheus,loki,alerting,dashboard,folder,oncall,asserts,pyroscope,navigation,tempo,annotations,rendering,snapshot,docs

Categories not in that default string are off until you add them, including: admin, agento11y, assistant, elasticsearch, cloudwatch, cloudlogging, examples, sql, influxdb, quickwit, and runpanelquery. Pass a full comma-separated list to replace the default entirely, or use --disable-* flags to turn off pieces of the default set. Back-compat aliases clickhouse, snowflake, and athena map to sql; proxied maps to tempo.
--disable-search: Disable search tools.
--disable-datasource: Disable datasource tools.
--disable-incident: Disable incident tools.
--disable-prometheus: Disable Prometheus tools.
--disable-write: Disable write tools (read-only mode; refer to the following section).
--disable-query: Disable query tools (tools that execute a query against a datasource; refer to the following section).
--enable-query: Keep the raw-SQL query tools registered under --disable-write (refer to the following section).
--enable-write-tools: Comma-separated list of individual tool names to keep registered under --disable-write, for example, query_sql, query_influxdb, or generate_deeplink. Has no effect on a tool whose whole category is disabled.
--disable-loki: Disable Loki tools.
--disable-elasticsearch: Disable Elasticsearch tools.
--disable-quickwit: Disable Quickwit tools.
--disable-influxdb: Disable InfluxDB tools.
--disable-alerting: Disable alerting tools.
--disable-dashboard: Disable dashboard tools.
--disable-folder: Disable folder tools.
--disable-oncall: Disable OnCall tools.
--disable-asserts: Disable Asserts tools.
--disable-admin: Disable admin tools.
--disable-pyroscope: Disable Pyroscope tools.
--disable-navigation: Disable navigation (deeplink) tools.
--disable-rendering: Disable rendering tools (panel or dashboard image export).
--disable-snapshot: Disable snapshot tools.
--disable-cloudwatch: Disable CloudWatch tools.
--disable-cloudlogging: Disable Google Cloud Logging tools.
--disable-examples: Disable query examples tools.
--disable-sql: Disable SQL datasource tools (ClickHouse, Snowflake, Athena, MySQL, PostgreSQL, MSSQL). Aliases --disable-clickhouse, --disable-snowflake, --disable-athena also work.
--disable-runpanelquery: Disable run panel query tools.
--disable-annotations: Disable annotation tools.
--disable-tempo: Disable Tempo tracing tools.
--disable-provisioning: Disable provisioning tools.
--disable-agento11y: Disable Agent Observability tools.
--disable-assistant: Disable Grafana Assistant tools.
--disable-docs: Disable documentation tools.
--disable-user: Disable user info tools.

Configure tool limits

--max-loki-log-limit: Maximum number of log lines returned per query_loki_logs call.
--loki-guardrail-mode: Loki query cost guardrail for query_loki_logs: off (default), shadow (log queries that would be blocked, but let them run), or enforce (reject them with rewrite guidance). The guardrail requires a selective stream selector, caps the effective time range (including range-vector durations like [30d]), and pre-checks Loki’s index/stats byte estimate before running the query. On VictoriaLogs it applies only to selector-shaped ({...}) queries — brace-less LogsQL passes through entirely and the byte-budget check never applies. Falls back to the GRAFANA_LOKI_GUARDRAIL_MODE environment variable.
--loki-guardrail-max-bytes: Maximum bytes a single query_loki_logs call may scan, estimated via Loki’s index/stats API. Defaults to 100 GiB; 0 disables the byte-budget check. Falls back to GRAFANA_LOKI_GUARDRAIL_MAX_BYTES.
--loki-guardrail-max-range: Maximum effective time range for a single query_loki_logs call, including range-vector durations. Defaults to 24h; 0 disables the range check. Falls back to GRAFANA_LOKI_GUARDRAIL_MAX_RANGE.

The guardrail’s decisions are also exported as OTel counters (mcp_loki_guardrail_admitted_total, _would_block_total, _blocked_total, _fail_open_total), which is the recommended way to size the affected population before promoting from shadow to enforce. See Observability.

--dynamic-multi-org: Allow tool calls to select a Grafana organization per call via an optional orgId argument. Off by default. See Multi-organization support.

Run without query execution

--disable-query removes every tool that executes a query against a datasource, and leaves the metadata and discovery tools in place.

Use it when the assistant should be able to explore what exists — datasources, dashboards, metric names, labels, table schemas — without running potentially expensive or data-revealing queries; for example, with a service account that has datasources:read but not datasources:query.

The following tools are not registered when the flag is set:

Prometheus: query_prometheus, query_prometheus_histogram
Loki: query_loki_logs, query_loki_patterns (query_loki_stats and analyze_loki_labels read the index rather than returning log content, so they stay registered)
Elasticsearch and OpenSearch, Quickwit: query_elasticsearch, query_quickwit
SQL datasources: query_sql, query_influxdb
Graphite: query_graphite, query_graphite_density
CloudWatch: query_cloudwatch
Google Cloud Logging: query_cloud_logging
Pyroscope: query_pyroscope
Panels: run_panel_query

The elasticsearch, quickwit, influxdb, and runpanelquery categories contain nothing else, so they expose no tools at all when queries are disabled. Sibling tools such as list_prometheus_metric_names, list_loki_label_values, describe_sql_table, list_cloudwatch_metrics, and list_cloud_logging_projects remain available.

The flag gates the query tools and the grafana_api_request POST-to-/api/ds/query path, but doesn’t police every route to a datasource. In read-only mode, grafana_api_request allows POST to /api/ds/query only when query tools are enabled (same gate as the raw-SQL tools — blocked by --disable-write unless --enable-query overrides). get_panel_image, which renders a panel server-side, is unaffected.

Query execution and read-only mode

The raw-SQL query tools — query_sql and query_influxdb — send the query to the datasource unfiltered, so they write whenever the datasource credentials permit it. Read-only mode removes them along with the other write tools.

--enable-query puts them back. Use it when the datasource credentials are known to be read-only and you want query execution in an otherwise read-only server. It doesn’t re-enable any other write tool, and it has no effect alongside --disable-query, which always wins.

Flags	Safe query tools	Raw-SQL query tools
(none)	Registered	Registered
`--disable-write`	Registered	Not registered
`--disable-write --enable-query`	Registered	Registered
`--disable-query`	Not registered	Not registered
`--disable-query --enable-query`	Not registered	Not registered

Restrict which Loki streams can be read

--loki-enforced-matchers: LogQL label matchers AND-ed into every native-Loki query to restrict which log streams can be read (e.g. environment=~"prod|staging"). Unparseable queries are rejected; VictoriaLogs datasources are refused while set.
--loki-label-enumeration-fallback: What the label-enumeration tools do when negative enforced matchers can’t scope them: reject (default) or unfiltered.

Warning
Enforcement applies only to the Loki query tools. Other tools can reach Loki log data through paths that never touch the enforced backend, so you must also disable them for the restriction to hold:

--disable-api: grafana_api_request can query the Loki datasource proxy directly (full bypass).

--disable-rendering: get_panel_image renders Loki panels server-side, producing images with unrestricted log lines.

--disable-assistant: ask_assistant delegates to Grafana Assistant, which reads Loki server-side across all streams. It is only registered when write tools are enabled, so --disable-write closes it too.

The server logs a warning at startup naming each of these that is still enabled. run_panel_query is safe: it routes on the datasource’s real type resolved from its UID, so a Loki datasource always runs through the enforced query path even if the panel or the caller declares a different datasourceType. Tempo tools expose only traces, not Loki logs, so they are not a bypass. Dashboard snapshots (--disable-snapshot) can embed log-panel data captured outside enforcement.

Run in read-only mode

--disable-write prevents write operations to Grafana. Use it with read-only service accounts, safer production assistants, or to avoid accidental changes. It also removes the raw-SQL query tools, which can write through the datasource; refer to the preceding section for --enable-query, which keeps them.

In read-only mode, generate_deeplink ignores shorten=true and returns the full URL, because Grafana creates short URLs through POST /api/short-urls. Add --enable-write-tools=generate_deeplink to keep URL shortening without re-enabling any other write tool.

When enabled, the following writes are disabled:

Dashboard tools

update_dashboard

Folder tools

create_folder

Incident tools

create_incident
add_activity_to_incident
update_incident

Alerting tools

alerting_rules_write (create, update, delete)
alerting_silences_write (create, update, delete)
alerting_routing_write (create_contact_point)

OnCall tools

update_alert_group

Annotation tools

create_annotation
update_annotation
delete_annotation

Snapshot tools

create_snapshot
delete_snapshot

Agent Observability tools

agento11y_manage_evaluators (upsert, delete, fork, and test evaluators)
agento11y_manage_eval_rules (create, update, delete, and preview eval rules and guards)
agento11y_manage_eval_collections (save and delete saved conversations; create, update, and delete collections; add and remove collection members)
agento11y_manage_experiments (update and cancel experiments)
agento11y_manage_test_suites (create and update test suites; create and publish versions; upsert and delete test cases)

Read operations (queries, lists, searches) stay available.

Configure Grafana HTTP redirects

Outbound Grafana clients block redirects to a different scheme, host, or port by default. Use --allow-cross-origin-redirects or set GRAFANA_ALLOW_CROSS_ORIGIN_REDIRECTS=true to allow them. The flag takes precedence over the environment variable. Allowing these redirects can send Grafana credentials to the redirect target. Request-selected Grafana URLs remain pinned to their selected target.

Configure client TLS for Grafana

--tls-cert-file: Client certificate for mTLS to Grafana.
--tls-key-file: Client private key.
--tls-ca-file: CA certificate for verifying Grafana’s server certificate.
--tls-skip-verify: Skip TLS verification (insecure; testing only).

Configure server TLS for streamable-http

These flags secure the MCP HTTP server (between your MCP client and mcp-grafana), not the connection from mcp-grafana to Grafana:

--server.tls-cert-file: Server certificate for HTTPS.
--server.tls-key-file: Server private key.

Print version information

--version: Print the version and exit.

Next steps

Health check endpoint

Thu, 03 Sep 2026 07:21:20 +0000

Health check endpoint

When you use the SSE (-t sse) or streamable HTTP (-t streamable-http) transport, the MCP server exposes a health check at /healthz. Load balancers, monitoring, and orchestration can use it to verify that the server is running and accepting connections.

What you’ll achieve

You can probe readiness from scripts or upstream checks when the server uses an HTTP transport.

Before you begin

The server running with -t sse or -t streamable-http (not stdio).

Send a health check request

Endpoint: GET /healthz

Response:

Status code: 200 OK
Body: ok

Examples:

# For streamable HTTP or SSE transport with default listen address (localhost:8000)
curl http://localhost:8000/healthz

# Health check on a separate listen address (for example Kubernetes probes
# while --address is bound to 127.0.0.1 behind a sidecar)
./mcp-grafana -t streamable-http --address 127.0.0.1:8000 --healthz-address :8080
curl http://localhost:8080/healthz

The /healthz handler only reports that the HTTP server is up; it does not check Grafana connectivity. A --healthz-address listener is not wrapped by --allowed-hosts / --allowed-origins validation, matching --metrics-address.

Note: The health check endpoint is only available when using SSE or streamable HTTP transports. It is not available with the stdio transport (-t stdio), because stdio does not start an HTTP server.