Dashboards¶
dashboard_write turns PromQL into a Grafana dashboard document in your
organization's Grafana, owned by the member who asked for it;
dashboard_read lists the documents you can show. Both are tools on the
MCP server, single phase: no preview, no confirm_token. They
exist so an agent shows monitoring in Grafana's own UI, live, instead of
a hand-drawn page. The numbers behind a chart come from
metrics_query, which
runs the same expressions.
Documents¶
One document per chart. Every create writes a new dashboard with its
own uid (marshall- followed by 12 hex characters) into a Marshall
folder of your organization's Grafana org, tagged marshall,
member:<your username> and scratch or kept. Several charts at once
are several panels in one document or several documents. The document
is not editable in Grafana: every change goes through dashboard_write.
Ownership is by member. update, keep and delete act only on
documents you created; another member's uid is refused as 404
not-found, the same answer a missing uid gets. Every document is
visible to the whole organization in Grafana, like every dashboard
there; the tool enumerates only your own.
Every panel reads your organization's own monitoring and nothing else: the datasource is pinned to your organization's tenant, and PromQL has no syntax for another one.
Scratch and kept¶
A new document is scratch: it expires 24 hours after its last use
and is then deleted from Grafana. An update, a dashboard_read get,
or a console pane showing it counts as use. keep names the document,
moves it to the Saved folder under Marshall and removes the expiry;
the uid does not change, so links stay valid. delete removes a
document at once, scratch or kept; there is no undo, but nothing beyond
the document is lost.
| Limit | Value |
|---|---|
| Scratch expiry | 24 hours after last use (currently) |
| Scratch documents per member | 20 |
| Scratch documents per organization | 200 |
| Panels per document | 12 |
| Queries per panel | 8 |
| PromQL per query | 4000 characters |
| Title | 120 characters |
Kept documents do not count against the scratch caps.
dashboard_write¶
| Argument | Values | Meaning |
|---|---|---|
action |
create, update, keep, delete |
required |
dashboard |
a uid of your own | required for update, keep, delete |
title |
at most 120 characters | required on create; renames on update and keep |
panels |
1 to 12 panel specs, below | required on create; replaces the panels on update |
range |
1h, 6h, 24h, 7d (default 6h) |
the window the dashboard opens on |
update takes any of title, panels, range and carries the rest
over from the document; at least one is required. keep on a kept
document renames it.
A panel spec is {title, kind, queries, unit?, thresholds?}:
| Field | Values | Meaning |
|---|---|---|
title |
at most 120 characters | the panel title |
kind |
timeseries, stat, gauge, bargauge, table |
lines over the window; one number; a gauge; one bar per series; an instant read as rows |
queries |
1 to 8 of {expr, legend?} |
PromQL, at most 4000 characters each; legend is a Grafana legend template such as {{instance}} |
unit |
a Grafana unit id (percent, celsius, bytes, watt, short, …) |
optional |
thresholds |
up to 4 ascending numbers | optional; colors the panel green below the first, then yellow, orange, red |
The answer carries dashboard (the uid), title, folder (scratch
or saved), panels ([{id, title, kind}], ids 1..n), range,
version, created_at, last_used_at, expires_at (null once
kept), url (the document in your organization's Grafana) and
member_signed_in. member_signed_in is false when you have never
opened Grafana: the first visit to the URL signs you in once, and
charts render after that; null means the server could not tell.
delete answers {dashboard, title, deleted: true}.
dashboard_read¶
| Argument | Values | Meaning |
|---|---|---|
action |
list, get |
required |
dashboard |
a uid | required for get |
list answers dashboards (your own documents, the shape above),
platform (the platform's tenant dashboards in your organization's
Grafana, each with uid, title, tags, panels [{id, title,
kind}], variables [{name, label, hidden, current}] and url),
caps (scratch_used, scratch_cap, org_scratch_used,
org_scratch_cap), scratch_ttl_s and member_signed_in. Other
members' documents are not listed.
get on your own uid answers the document with its spec (the panels
as given) and counts as use; get on a platform dashboard's uid answers
its panels and variables.
Refusals¶
| Code | When | What to do |
|---|---|---|
bad-request (422) |
a missing title or panels, an unknown kind or action, an expression over 4000 characters, more than 12 panels or 8 queries; Grafana refused the composed document (its message is in detail) |
fix the spec |
not-found (404) |
a uid that does not exist or is another member's | dashboard_read list names yours |
dashboard-cap (409) |
the per-member or per-organization scratch cap; detail names the least recently used scratch document and oldest carries its uid |
keep or delete one, then retry |
grafana-unavailable (503) |
Grafana did not answer, or your organization has no Grafana org yet | retry shortly; the org appears with its first monitored cluster |
dashboards-unavailable (503) |
the environment has no dashboard store | none; the surface is off there |
The member rate limit and every other rule in MCP server apply.