---
title: "Command-line flags | Grafana documentation"
description: "CLI flags for the mcp-grafana binary, including transports, tools, TLS, and read-only mode."
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# 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](/docs/grafana-cloud/ai-tools/mcp-servers/oss-mcp/set-up/install-the-binary), [`uvx`](/docs/grafana-cloud/ai-tools/mcp-servers/oss-mcp/set-up/install-with-uvx), or a [container](/docs/grafana-cloud/ai-tools/mcp-servers/oss-mcp/set-up/install-with-docker).

## 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.
- `--endpoint-path`: HTTP path for the streamable-http MCP endpoint. Default: `/mcp`.
- `--session-idle-timeout-minutes`: Idle timeout for streamable-http sessions, in minutes. Sessions with no activity for this duration are automatically reaped. Set to `0` to disable. Default: `30`.

## Configure HTTP transport security

The SSE and streamable-http transports validate `Host` and `Origin` headers on every route (`/sse`, `/mcp`, `/healthz`, `/metrics`) to block DNS-rebinding attacks. Stdio transport is unaffected.

- `--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 the check — only safe behind a trusted reverse proxy that rewrites `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 (or `*` if the proxy is fully trusted). Kubernetes `httpGet` liveness/readiness probes send `Host: <pod-ip>:<port>` by default — either set `--allowed-hosts '*'`, override the probe’s `host:` field, or use a `tcpSocket` probe. External `/metrics` scrapes must add the scrape source’s `Host` to the allowlist (or use `--metrics-address` to bind metrics on a separate port, which is unaffected).

## 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:

Expand table

| 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](/docs/grafana-cloud/ai-tools/mcp-servers/oss-mcp/configure/server-tls-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.

## 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.

## 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,sift,pyroscope,navigation,proxied,annotations,rendering,snapshot`
  
  Categories **not** in that default string are off until you add them, including: `admin`, `agento11y`, `assistant`, `elasticsearch`, `cloudwatch`, `examples`, `clickhouse`, `snowflake`, `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.
- `--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-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-sift`: Disable Sift 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-examples`: Disable query examples tools.
- `--disable-clickhouse`: Disable ClickHouse tools.
- `--disable-snowflake`: Disable Snowflake tools.
- `--disable-runpanelquery`: Disable run panel query tools.
- `--disable-annotations`: Disable annotation tools.
- `--disable-proxied`: Disable proxied tools (tools from external MCP servers).
- `--disable-provisioning`: Disable provisioning tools.
- `--disable-agento11y`: Disable Agent Observability tools.
- `--disable-assistant`: Disable Grafana Assistant tools.

## Configure tool limits

- `--max-loki-log-limit`: Maximum number of log lines returned per `query_loki_logs` call.

## 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.

When enabled, the following writes are disabled:

**Dashboard tools**

- `update_dashboard`

**Folder tools**

- `create_folder`

**Incident tools**

- `create_incident`
- `add_activity_to_incident`

**Alerting tools**

- `alerting_manage_rules` (create, update, delete)

**Annotation tools**

- `create_annotation`
- `update_annotation`

**Sift tools**

- `find_error_pattern_logs` (creates investigations)
- `find_slow_requests` (creates investigations)

**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 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

- [Enable and disable tools](/docs/grafana-cloud/ai-tools/mcp-servers/oss-mcp/configure/enable-and-disable-tools)
- [Client TLS (Grafana connection)](/docs/grafana-cloud/ai-tools/mcp-servers/oss-mcp/configure/client-tls-grafana-connection)
- [Server TLS (streamable-http)](/docs/grafana-cloud/ai-tools/mcp-servers/oss-mcp/configure/server-tls-streamable-http)
- [Transports and addresses](/docs/grafana-cloud/ai-tools/mcp-servers/oss-mcp/configure/transports-and-addresses)