Grafana MCP server: tools, limits and setup

Grafana's 119-tool official server reaches metrics, logs and dashboards, and its replies turn partial at documented limits.

Checked 1 September 2026 · from Grafana's documentation and public repositories

One of 91 guides to monitoring and developer tools. Each covers what an AI coding agent can get out of the tool through MCP, the protocol that lets the agent query the tool directly.

What is the Grafana MCP server?

Grafana's first-party server has 119 tools for dashboards, metrics, logs and traces. MCP is an open protocol that lets an AI coding agent call a tool's functions, such as running a PromQL query, without anyone writing code against the tool's API.

You run a small binary, or point at Grafana's hosted endpoint, and the agent gains a set of tools: run this PromQL query (PromQL is Prometheus's query language), search these logs, read that dashboard. The tools are grouped into categories you enable by name, and the agent picks tools on its own based on what you ask in English.

Grafana covers production observability broadly, and agent observability partially.

For an agent, Grafana answers questions about the systems your code runs on. It says almost nothing about your own agents, unless you are on Grafana Cloud and you turn the agent tools on. An agent connected here can investigate an incident end to end. It cannot tell you what your own agents cost or how their prompts changed.

What can an AI agent do with Grafana?

Asking in English is not one call. Your agent takes the question, then runs schema discovery: list_prometheus_metric_names or get_dashboard_panel_queries, to find the real metric and label names. It writes PromQL from those names, then calls query_prometheus with it. Prefer the dashboard route, because panel queries are the queries your team already wrote. The agent copies your naming conventions instead of guessing them.

What the tool definitions cost in context

A client that loads every tool definition at the start of a session spends this much context before the first question. Claude Code defers definitions by default through tool search, and loads a tool's definition when the agent needs it. The method below gives the version and date measured.

A context window is the amount of text a model can hold at once. A client that loads every tool definition upfront sends each tool's name, description and input schema to the model when the session starts. That list is charged whether or not a single tool is called.

Grafana does not publish this figure, and neither does any other vendor in this guide. The counts below were measured from the server's own tools/list response, which is the exact JSON a client receives.

The figures are a dated measurement of v1.1.0 from August 2026, when the default set was 65 tools and the full set 105. v2.0.0 registers more tools: 79 by default and 119 in all.

Encodings: GPT-5.6, GPT-5.5 o200k_base; GPT-4, GPT-3.5 cl100k_base; Claude Haiku 4.5 to Opus 5 count_tokens. Counted 18 August 2026 from mcp-grafana v1.1.0's tools/list, run locally.

Registration is static, so no account was needed. Figures cover each tool's name, description and input schema. The two models in column one share the o200k_base encoding, so they get one count. The spread is formatting: compact JSON at the low end, indented at the high end, about 35% apart. Reasoning tokens are output, spent per request. The tool list is billed as input whenever the client loads it.

The Claude figures are measured rather than encoded. Anthropic publishes no local tokenizer, so the definitions were sent to the API's count_tokens endpoint and a no-tools baseline subtracted. The range covers two tokenizer generations rather than two serializations. Haiku 4.5 and Opus 4.6 sit at the low end, Opus 5 and Sonnet 5 at the high end. The gap between them is about a third.

Can Grafana watch your own AI agents?

Grafana Cloud added Agent Observability tools to the connector in July 2026. They are disabled by default and work only in Grafana Cloud; enable them by adding agento11y to --enabled-tools. Checked against the repository README, retrieved 13 August 2026.

Write operations in this group (eval rules, saved conversations, test suites) need the grafana-agento11y-app.eval:write permission, granted by the Agento11y Admin role.

Grafana MCP server limits: where answers come back incomplete

Grafana documents each boundary below. A series cap returns HTTP 400. A timeout announces itself. The log-line cap, the Adaptive features and the client output limit are all silent. The agent answers confidently in every case.

How to configure Grafana MCP for agents

1. 1

   Decide on write access first

   --disable-write is a true server-side flag. Since v2.0.0, alerting has separate read and write tools, so read-only mode keeps alert rules, silences and routing readable. It removes dashboard edits, incident and annotation writes, snapshots and the raw-SQL query tools. --enable-write-tools restores single write tools by name.

2. 2

   Trim the tool list

   Use --enabled-tools. On v2.0.0 the default enables 79 tools across 22 categories. Unless the client defers tool loading, each definition takes part of the context window before any data arrives.

3. 3

   Choose local or hosted

   Local runs the binary with a service account token. Hosted is mcp.grafana.com/mcp with OAuth, and it is billable. Grafana's pricing page states that connecting through the Cloud MCP server counts you as an active AI user for that billing period, even if your token usage is zero. The rate is $20 a month after three free seats.

Paste this into your agent’s instructions

This block makes the agent report its time range, and for Loki the number of series a query touched.

When you query Grafana, always report alongside your answer:
- The time range you queried. On Grafana Cloud, logs allow
  30 days plus 1 hour and metrics allow 32 days; self-hosted
  ranges are set locally.
- For Loki queries: the number of series involved. A failure on
  a broad query usually means the 500-series cap, not missing data.
- The number of log lines returned and the limit you set. The
  default is 10; the maximum is 100; there is no pagination.
- The metric resolution you received. Cloud Pro returns one
  point per minute.
- Whether Adaptive Metrics, Logs or Traces are enabled, if known.
  A missing label or trace may have been dropped by them.
Never state that data does not exist. State that no data was
returned under the constraints above.
Write your answer in ASD-STE100 Simplified Technical
English. Use short sentences with one idea in each.

Do you need the MCP server at all?

Not strictly. Prometheus and Loki have open HTTP APIs, and a coding agent can query them directly, skipping Grafana entirely. For self-hosted stacks, direct API access gives full control of ranges and limits, though the agent must construct every request itself.

What MCP adds is everything around the queries. Dashboard introspection reads your panels, which teaches the agent your conventions, and the raw datasource APIs do not. Traces, incidents and on-call arrive in the same conversation. Grafana's own tool descriptions tell the agent what each tool is for.

Use MCP for investigation work and dashboard context, and the datasource APIs for bulk or scripted pulls.

Grafana MCP server setup

All local setups need two things: the mcp-grafana binary on your PATH (or Docker), and a Grafana service account token. GRAFANA_API_KEY still works but is deprecated. Grafana 9.0 or later is required for full functionality.

claude mcp add-json "grafana" '{"command":"mcp-grafana","args":[],
  "env":{"GRAFANA_URL":"https://your-org.grafana.net",
         "GRAFANA_SERVICE_ACCOUNT_TOKEN":"<your-token>"}}'

{"mcpServers":{"grafana":{"command":"mcp-grafana","args":[],
  "env":{"GRAFANA_URL":"https://your-org.grafana.net",
         "GRAFANA_SERVICE_ACCOUNT_TOKEN":"<your-token>"}}}}

[mcp_servers.grafana]
command = "mcp-grafana"
env = { GRAFANA_URL = "https://your-org.grafana.net",
        GRAFANA_SERVICE_ACCOUNT_TOKEN = "<your-token>" }

Every other client

Each block below is the configuration for one client, with the file path and the key that client expects.

{"mcpServers":{"grafana":{"command":"mcp-grafana","args":[],
  "env":{"GRAFANA_URL":"https://your-org.grafana.net",
         "GRAFANA_SERVICE_ACCOUNT_TOKEN":"glsa_..."}}}}

{"mcpServers":{"grafana":{"command":"mcp-grafana","args":[],
  "env":{"GRAFANA_URL":"https://your-org.grafana.net",
         "GRAFANA_SERVICE_ACCOUNT_TOKEN":"glsa_..."}}}}

{"servers":{"grafana":{"command":"mcp-grafana","args":[],
  "env":{"GRAFANA_URL":"https://your-org.grafana.net",
         "GRAFANA_SERVICE_ACCOUNT_TOKEN":"glsa_..."}}}}

{"mcpServers":{"grafana":{"command":"mcp-grafana","args":[],
  "env":{"GRAFANA_URL":"https://your-org.grafana.net",
         "GRAFANA_SERVICE_ACCOUNT_TOKEN":"glsa_..."}}}}

Read-only access, permissions and security

• Read-only

  Run with --disable-write, a true server-side flag. On v2.0.0 it keeps every read tool, including alert rules and silences.

• Scope the token

  The service account's permissions are the agent's permissions. Grant viewer-level access unless the agent needs to write dashboards or open incidents. That advice covers self-hosted; on the hosted endpoint the account also needs the Assistant Cloud MCP User role, whatever its permission level.

• Open issues worth knowing

  Token rotation fails silently on stdio (#987), and stdio is the transport CLI agents usually use. Observability data can carry prompt injection (#680). Telemetry an agent reads can contain adversarial text. #1048 said the SSE and streamable-HTTP transports do not authenticate the client. It was closed on 25 August 2026 as intended behavior. The maintainer states that a server started with configured service-account credentials falls back to those.

Troubleshooting

400 on a broad query

The cause is the 500-series cap. Scope by namespace or service and aggregate in steps.

Everything times out at exactly 10 seconds

The cause is the connector's own 10-second default. Raise --grafana-timeout. The backend limits behind it are 30 seconds to 2 minutes.

401 on connect

The cause is an expired or under-scoped service-account token, or the wrong Grafana URL. On the hosted endpoint, check that the connecting user has the Assistant Cloud MCP User role.

Tools are missing in the client

Check --enabled-tools. The v2.0.0 default is 22 categories, and anything trimmed from that list never reaches the agent. Read-only mode removes the write tools by design. The Sift tools and the sift category were removed in v2.0.0.

Output arrives cut off

Usually the client. Claude Code caps MCP output at 25,000 tokens by default; raise MAX_MCP_OUTPUT_TOKENS.

Grafana MCP server: Reference

What engineers report

The connector has 3,525 stars, 460 forks and roughly 3.7M Docker pulls as of 6 October 2026. Public discussion still covers the Grafana platform far more than the connector. One of the three quotes below is about the connector; the other two are about the platform it queries. In the platform comments, the core products are praised for stability and the surrounding pieces are criticized for churn. The collection agent alone has been renamed from Agent to Agent Flow to Alloy.

“The criticisms brought by Chris are valid, and it's good feedback. ... while I know for a fact there are hundreds to thousands of folks out there who are successfully running Loki ... it can be very rough around the edges.”

“Giving Amp/Claude Code the Grafana MCP + read-only kubectl has saved me days worth of debugging.”

“I've had a grafana + prometheus setup on my servers since like 2017. It worked then and works today.”

Should you connect an agent to Grafana?

Yes. Best for teams on Grafana's LGTM stack (Loki, Grafana, Tempo, Mimir) who will configure the connector deliberately: raised timeout, trimmed categories, and the instructions above pasted into the agent.

Strongest fit

Self-hosted Prometheus and Loki shops that want an agent investigating with the tools the team already uses, plus dashboard introspection.

Main advantage

A first-party, long-running connector: 119 tools, 71 releases, eight documented clients, and a true server-side read-only flag.

Main weakness

On Grafana Cloud, result caps and the Adaptive features silently shrink what the agent sees, and a query that spans every host fails outright at 500 series.

Operational risk

Version 2.0.0 removed the Sift tools and renamed the alerting tools, so scripts that call the old names break. On the hosted endpoint, merely connecting is a billable seat.

Frequently asked questions