Provides tools for interacting with the Prometheus HTTP API, including instant and range PromQL queries, metric and label discovery, alert and rule inspection, scrape target health, TSDB cardinality status, and optional admin operations such as series deletion, tombstone cleanup, and configuration reload.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-prometheus show me firing alerts and any unhealthy scrape targets"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol server for the Prometheus HTTP API: PromQL queries, metric and label discovery, alerts, rules, scrape health and cardinality, shaped to fit a context window.
The server is read-only by default. The admin tools are not merely refused when writes are off — they are never registered, so an agent cannot call them at all.
Prometheus answers are built for dashboards, not for models. Measured on a kube-prometheus-stack install (~800k head series, 268 targets):
Endpoint | Raw | What this server returns |
| 1.5 MB | totals, unhealthy pools, and the unhealthy targets with |
| 9 labels repeated per series | shared labels once in |
|
| one array per series on the step grid, rounded, plus min/max/avg/last |
| 200 KB | flat list, filterable by health/state/type/name |
| 420 KB | searched by name and help text, cached |
It also does the things a model gets wrong on its own: relative times (now-1h), a round
step picked for ~60 points, label lookups limited to series that exist now rather than over
the whole retention, and PromQL errors returned verbatim with what to do about them.
Related MCP server: Kubernetes Read Only MCP Server
Tool | What it does | Writes |
| Which Prometheus answered (version, hostname, external labels, retention, admin API), or what to configure | no |
| Instant PromQL query | no |
| Range query on a step grid, with per-series stats; | no |
| Find metrics by name or help text, with type and help | no |
| Type, help, series count, and every label with its cardinality and examples | no |
| Label names, optionally on a selector | no |
| Values of one label, optionally on a selector | no |
| Firing and pending alerts, most severe first, with counts | no |
| Alerting and recording rules; | no |
| Scrape health: totals, unhealthy pools and targets with their errors | no |
| Head-block cardinality: top metrics, labels, label pairs | no |
| GET any | no |
| Delete series (counts first, refuses past | yes |
| Purge deleted data from disk (needs | yes |
|
| yes |
There is deliberately no /-/quit and no TSDB snapshot tool (a snapshot copies the whole TSDB
onto a volume sized for one).
Variable | Required | Description |
| yes | Base URL, including any path prefix ( |
| no | Basic auth for a proxy in front of Prometheus. |
| no | Bearer token instead of basic auth. |
| no | Extra headers as JSON, e.g. |
| no |
|
| no | Query timeout in seconds (default 30). |
| no | Retries for 429 and proxy 5xx (default 2). Query timeouts are never retried. |
| no |
|
A self-signed certificate needs NODE_EXTRA_CA_CERTS=/path/to/ca.pem.
A configuration mistake — a malformed URL, a token and basic auth, invalid
PROMETHEUS_HEADERS — never stops the server from starting. It starts with only
prometheus_auth_status, which says what to fix.
kube-prometheus-stack names everything identically on every cluster, so a .mcp.json copied
between projects answers every query with plausible numbers from the wrong one. The server
prints the instance it reached on startup (stderr), and prometheus_auth_status returns the
URL, version, hostname and external labels. If you run several clusters, set a distinguishing
external label (prometheus.prometheusSpec.externalLabels.cluster in kube-prometheus-stack).
pnpm install
pnpm buildThen copy .mcp.json.example to .mcp.json and fill it in.
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"cli","version":"0"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
| PROMETHEUS_URL=http://localhost:9090 node dist/cli.js 2>/dev/null | jq -r '.result.tools[]?.name'pnpm dev # tsdown --watch
pnpm test # vitest
pnpm typecheck
pnpm lint
pnpm formatpnpm dlx release-it # bump, commit, tag
git push --follow-tags # CI publishes to npm + GHCR from the tagMIT
Report which Prometheus this server talks to and whether it answers: the URL, auth mode, Prometheus version, hostname, external labels and retention, and whether the admin API is enabled. When the server is not configured, says exactly what to set. Call this first when a tool you expected is missing, and before trusting numbers from an instance you have not checked — kube-prometheus-stack installs look alike on every cluster, so the URL host is often the only tell.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint; the description goes further by disclosing the returned diagnostic fields and the not-configured failure mode ('says exactly what to set'). It stops short of describing output shape or latency, but for a read-only status probe this is well beyond the annotation bar.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with what it reports, then the not-configured behavior, then the when-to-call advice. No sentence is padding and the cautionary sentence carries real selection value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, yet the description enumerates the salient returned fields and the failure path, and it explains its role relative to the eleven query/list siblings. Nothing an agent needs before calling is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline of 4 applies; there is nothing further the description could add here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Report which Prometheus this server talks to') and enumerates the returned facts (URL, auth mode, version, hostname, external labels, retention, admin API flag), which clearly separates it from the query/list siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit triggers: 'Call this first when a tool you expected is missing' and 'before trusting numbers from an instance you have not checked'. It also explains why that check matters, kube-prometheus-stack installs looking identical across clusters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Everything needed to query one metric: type, help, unit, how many series it has, and each label with its number of distinct values and examples. Read this before writing a selector — it shows which labels exist to filter and group by, and whether a label is high-cardinality (pod, uid) and so a bad thing to group by.
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | Only consider series with samples before this: now, now-1h, -30m, an RFC3339 timestamp (2026-01-31T12:00:00Z) or unix seconds. Defaults to now. | |
| start | No | Only consider series with samples after this: now, now-1h, -30m, an RFC3339 timestamp (2026-01-31T12:00:00Z) or unix seconds. Defaults to now-1h, i.e. series that exist now. Pass now-30d to include ones that have since gone away. | |
| metric | Yes | A metric name, e.g. `http_requests_total`. For a histogram or summary, the base name (`http_request_duration_seconds`) covers its _bucket, _count and _sum series. | |
| examples | No | Example values to show per label (0-50). Defaults to 8. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuine behavioral value beyond that: it discloses the computed outputs (series count, distinct-value counts, examples) and calls out the practical consequence of high-cardinality labels (pod, uid) being bad group-by keys — insight an agent would otherwise have to derive itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the return contents and then the usage rationale. Dense but every clause carries information; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description properly enumerates what comes back (type, help, unit, series count, labels with counts and examples). The only omission is that results are scoped by the start/end window, which the schema covers but the description never hints at.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents metric naming (including histogram/summary base names), start/end time windows, and the examples count. The description adds nothing parameter-specific, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States specifically that it returns metadata for one metric: type, help, unit, series count, and per-label cardinality plus example values. This is clearly distinct from siblings like prometheus_query (executes a query) and prometheus_list_labels (enumerates label names), since the agent knows this is per-metric introspection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Read this before writing a selector" gives explicit ordering guidance for the agent's workflow, and the high-cardinality warning steers grouping decisions. It stops short of naming alternatives (list_metrics, list_labels, list_label_values) that could be used for adjacent discovery tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cardinality: how many series the head block holds, and which metrics, labels and label pairs account for most of them and of the memory. Use it to explain a slow or memory-hungry Prometheus, or before grouping by a label that might have thousands of values. Covers the head block only (the last ~2-3 hours), not the full retention.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Entries in each top-N list (1-100). Defaults to 10. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint, so the description carries most of the behavioral burden and does so well: it discloses the scope limitation that results cover the head block only (~2-3 hours) and not full retention — critical information that prevents misinterpreting the numbers. It doesn't mention cost or response volume for high-cardinality servers, which keeps it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with what the data is, then why to call it, then the scope caveat. Every sentence earns its place and nothing is repeated from the schema or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description must convey what comes back — and it does, describing ranked top-N breakdowns by metrics, labels, label pairs and memory. Combined with the explicit retention caveat, an agent has everything needed to call it and interpret results correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter has 100% schema description coverage, so the schema already explains limit, its 1-100 range and the default of 10. The description adds nothing about the parameter, so the baseline 3 for high-coverage schemas applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise characterization of the resource: cardinality of the head block, broken down by metrics, labels and label pairs, ranked by series count and memory. That is specific enough to distinguish it from prometheus_list_metrics or prometheus_describe_metric, which inspect individual metrics rather than aggregate cardinality. It stops short of explicitly naming siblings, so not a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives two concrete triggering scenarios: diagnosing a slow or memory-hungry Prometheus, and sanity-checking a label before grouping by it. That is clear when-to-use guidance. It does not say when NOT to use it or name the alternative tool for those cases, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the alerts Prometheus is currently firing or holding as pending, firing first and most severe first, with their labels, summary and description, plus counts by state and severity. This is Prometheus's own view: silences and inhibitions live in Alertmanager and are not applied here, so an alert listed here may not have paged anyone. An always-firing Watchdog alert is a heartbeat, not a problem.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum alerts to return (1-500). Defaults to 50. | |
| state | No | Only alerts in this state. Defaults to any. | any |
| search | No | Case-insensitive substring matched against the alert name, its label values and summary, e.g. a namespace. | |
| severity | No | Only alerts with this `severity` label, e.g. `critical`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds real behavior beyond readOnlyHint: default ordering (firing first, most severe first), the fields returned (labels, summary, description, counts by state and severity), and the crucial caveat that silences and inhibitions are not applied. Missing only finer points like pagination/truncation behavior when limit caps results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with what is returned and in what order, then interpretation caveats. No repetition of the tool name or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description covers the return shape, ordering, counts and the key interpretive trap, which is everything an agent needs to call this correctly and not misreport an alert as paging.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — limit, state, search and severity are all documented with defaults, bounds and an example. The description adds no parameter-level detail, so the schema does the work and the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (list alerts Prometheus is firing or holding pending) and immediately scopes it away from the neighboring rule/target tools by describing what the alerts carry. The `Watchdog` and Alertmanager remarks further separate it from generic query siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context on what the result means (Prometheus's own view, silences/inhibitions not applied, an alert here may not have paged anyone) and how to read the Watchdog heartbeat. It stops short of naming an explicit alternative tool for the Alertmanager view or when to prefer this over prometheus_query, so it is strong but not a full when/when-not map.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List label names, across everything or only on series matching a selector. To see one metric's labels with their values, prometheus_describe_metric is more useful.
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | Only consider series with samples before this: now, now-1h, -30m, an RFC3339 timestamp (2026-01-31T12:00:00Z) or unix seconds. Defaults to now. | |
| match | No | A series selector to restrict to, e.g. `{namespace="monitoring"}` or `up{job=~"kube.*"}`. A selector only — no functions or operators. An empty matcher set `{}` is rejected by Prometheus; use at least one non-empty matcher such as `{job=~".+"}`. | |
| start | No | Only consider series with samples after this: now, now-1h, -30m, an RFC3339 timestamp (2026-01-31T12:00:00Z) or unix seconds. Defaults to now-1h, i.e. series that exist now. Pass now-30d to include ones that have since gone away. | |
| search | No | Case-insensitive substring to filter by, e.g. `http`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes that this is a safe read operation. The description adds selector-scoping context, but it does not describe return ordering, pagination, or other behavioral details beyond what the schema and annotation provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action and scope. The alternative tool guidance follows immediately with no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with no required parameters, full schema coverage, and no output schema, the description is largely complete. It could say more about what the returned label names look like, but the essential invocation context is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains the selector, search, start, and end parameters in detail. The description mentions selector-based restriction but adds little beyond the structured parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: list label names. It also clarifies the scope, either across everything or restricted to series matching a selector, and distinguishes the tool from prometheus_describe_metric.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear usage context by explaining the two main modes: listing globally or using a selector. It also names prometheus_describe_metric as a more useful alternative for seeing one metric's labels with values, though it does not explicitly distinguish against every sibling such as prometheus_list_label_values.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the values one label takes — every namespace, job or instance — optionally only on series matching a selector (e.g. the pods of one deployment). Use it to get exact values right before filtering on them, instead of guessing at a regex.
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | Only consider series with samples before this: now, now-1h, -30m, an RFC3339 timestamp (2026-01-31T12:00:00Z) or unix seconds. Defaults to now. | |
| label | Yes | Label name, e.g. `namespace`, `job`, or `__name__` for metric names. | |
| limit | No | Maximum values to return (1-5000). Defaults to 200. | |
| match | No | A series selector to restrict to, e.g. `{namespace="monitoring"}` or `up{job=~"kube.*"}`. A selector only — no functions or operators. An empty matcher set `{}` is rejected by Prometheus; use at least one non-empty matcher such as `{job=~".+"}`. | |
| start | No | Only consider series with samples after this: now, now-1h, -30m, an RFC3339 timestamp (2026-01-31T12:00:00Z) or unix seconds. Defaults to now-1h, i.e. series that exist now. Pass now-30d to include ones that have since gone away. | |
| search | No | Case-insensitive substring to filter by, e.g. `http`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already declares this a safe read, so the description's burden is lower. It adds no behavioral context beyond that — no note on result volume, the limit cap's effect, or what happens with a broad match — leaving only the schema to cover those.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler; the operation and the optional selector scoping are front-loaded, and the second sentence earns its place by giving the concrete use case.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only lookup tool with a fully described six-parameter schema and an obvious return shape (a list of label values), the description covers purpose, scoping and intended use. Only the return shape's ordering/truncation behavior is left unaddressed, which is minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so start/end/limit/match/search are fully documented in the schema, which sets the baseline at 3. The description reinforces the selector concept with a deployment/pods example but adds no syntax or semantics not already present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — listing the values a single label takes — with concrete examples (namespace, job, instance) that pin down what a 'label value' is. It implicitly separates itself from prometheus_list_labels (label names) and prometheus_list_metrics, though it never names the sibling it is not.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear situational cue: use it to resolve exact values before filtering, rather than guessing at a regex. That tells the agent when to prefer this over trial-and-error filtering, but there is no explicit contrast with prometheus_list_labels or prometheus_query.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find metric names, with their type (counter, gauge, histogram, summary) and help text. search matches the name or the help text, so disk finds node_filesystem_avail_bytes by its description. Use this before writing a query against a metric you have not seen, then prometheus_describe_metric for its labels. Counters need rate() or increase(); summing a raw counter is the most common PromQL mistake.
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | Only consider series with samples before this: now, now-1h, -30m, an RFC3339 timestamp (2026-01-31T12:00:00Z) or unix seconds. Defaults to now. | |
| limit | No | Maximum metrics to return (1-1000). Defaults to 100. | |
| match | No | A series selector to restrict to, e.g. `{namespace="monitoring"}` or `up{job=~"kube.*"}`. A selector only — no functions or operators. An empty matcher set `{}` is rejected by Prometheus; use at least one non-empty matcher such as `{job=~".+"}`. | |
| start | No | Only consider series with samples after this: now, now-1h, -30m, an RFC3339 timestamp (2026-01-31T12:00:00Z) or unix seconds. Defaults to now-1h, i.e. series that exist now. Pass now-30d to include ones that have since gone away. | |
| search | No | Case-insensitive substring to filter by, e.g. `http`. | |
| metadata | No | Include type and help per metric. false returns bare names, about a fifth the size. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as read-only, and the description adds useful behavioral context: search matches both metric name and help text, metadata=false returns much smaller bare-name output, and raw counters require rate() or increase(). It does not cover auth or rate-limit behavior, but for a read-only list tool this is substantial added context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then adds search semantics, workflow guidance, and a counter caveat in four efficient sentences. There is no redundant restatement of schema fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a six-parameter read-only listing tool with fully documented schema and no output schema, the description is complete enough: it states what is returned, how search works, when to use it, and which sibling handles labels. Remaining details such as time ranges and limits are already covered in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all six parameters. The description adds value beyond the schema by explaining that `search` matches help text as well as metric names and by clarifying the downstream label lookup path.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: it finds metric names and returns their type and help text. It clearly distinguishes the tool from prometheus_describe_metric by directing label lookup to that sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit usage guidance: use this before writing a query against an unseen metric, then use prometheus_describe_metric for labels. It also adds a relevant PromQL warning about counters, making the when-to-use guidance actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List alerting and recording rules with their PromQL, health and state. Use health=err to find rules that fail to evaluate (their lastError says why) — a broken alert rule never fires, which looks exactly like everything being fine. Use type=record to find a recording rule's name before querying it, since a precomputed series is far cheaper than recomputing it.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Only alerting or only recording rules. Defaults to any. | any |
| group | No | Only rules in this rule group, by exact name. | |
| limit | No | Maximum rules to return (1-1000). Defaults to 50. | |
| state | No | Only alerting rules in this state. Defaults to any. | any |
| health | No | Only rules with this evaluation health. err = the last evaluation failed. | any |
| search | No | Case-insensitive substring matched against rule name, group and query, e.g. a metric name. | |
| include_query | No | Include each rule's PromQL. false roughly halves the size when only names are needed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes that this is a safe read operation, and the description adds useful behavioral context: failed evaluations expose lastError, broken alert rules never fire, and precomputed recording series are cheaper than recomputation. It does not describe pagination or output shape, but the added operational insight is substantial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three tightly structured sentences, front-loaded with the core action and followed by high-value usage notes. The explanatory clauses about broken alerts and precomputed series earn their place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a seven-parameter read-only list tool with no output schema, the description covers the core purpose and the two most operationally important filters. It leaves pagination, search, and group behavior to the schema, which is acceptable given full schema coverage but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema for key filters: health=err points to failed evaluations and lastError, and type=record explains why recording rules are useful to locate before querying.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource: lists alerting and recording rules, including PromQL, health, and state. It also distinguishes practical use cases from siblings, notably using type=record before querying a precomputed series.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly explains when to use health=err to find broken rules and type=record to locate a recording rule before querying it. It does not explicitly contrast with prometheus_list_alerts or spell out when not to use this tool, so it falls short of full alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scrape health: what Prometheus is failing to collect, and why. Always returns totals and every scrape pool with an unhealthy target; then lists targets, by default only the unhealthy ones with their lastError (a 404 is usually a wrong metrics path or port, a timeout a slow exporter, connection refused a pod not listening). A target that is down means its metrics stop — queries over it go quiet rather than erroring. Only active targets: the dropped ones (filtered out by relabeling) run to megabytes and are never fetched.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum targets to list (1-1000). Defaults to 50. | |
| health | No | Which targets to list. unhealthy (the default) = down or unknown; the totals always count all of them. | unhealthy |
| search | No | Case-insensitive substring matched against pool, instance, job and label values, e.g. a namespace. | |
| scrape_pool | No | Only this scrape pool, by exact name, e.g. `serviceMonitor/monitoring/node-exporter/0`. Filtered by Prometheus, so it is also the cheap way to inspect one big pool. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint, so the description carries most of the burden and does well: it states the return shape is always totals plus every pool with an unhealthy target, that the default filter lists only unhealthy targets, how to interpret lastError strings, and that dropped targets are excluded due to size. It stops short of describing pagination/truncation behavior around the limit or any auth prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose (scrape health) is front-loaded, and the following sentences are dense with operational detail rather than filler. The lastError parenthetical is long but earns its place by teaching error interpretation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and only a readOnlyHint annotation, the description adequately covers return structure at a high level (totals, pools, targets with lastError), the default filtering behavior, and the exclusion of dropped targets. Fine for an agent to call it correctly, though the exact fields of each target entry are not enumerated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so every parameter is already documented in the schema, making 3 the baseline. The description reinforces the health default and the scrape_pool shortcut but adds little syntax or interpretive detail beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific framing — 'Scrape health: what Prometheus is failing to collect, and why' — and names the concrete resource (scrape targets/pools). It is clearly distinct from siblings like prometheus_query, prometheus_list_metrics, and prometheus_get_tsdb_status, which cover querying, metric discovery, and storage rather than scrape health.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains when this tool matters — 'A target that is down means its metrics stop — queries over it go quiet rather than erroring' — implicitly telling the agent to reach for it when metrics are missing rather than querying. It also notes the scrape_pool filter as 'the cheap way to inspect one big pool' and that dropped targets are never fetched. No explicit 'use X instead' routing to a sibling, which keeps it below 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Evaluate a PromQL expression at one instant — the current value of something, or a total/average over a window written into the expression (increase(x[24h]), avg_over_time(x[1h])). This is the right tool for almost every question; use prometheus_query_range only when the shape over time matters. Labels shared by every series are returned once as common_labels. Upstream order is kept, so sort_desc() and topk() rank the result; past limit the rest is cut and truncated is set.
| Name | Required | Description | Default |
|---|---|---|---|
| time | No | Evaluation time: now, now-1h, -30m, an RFC3339 timestamp (2026-01-31T12:00:00Z) or unix seconds. Defaults to now. | |
| limit | No | Maximum series to return (1-2000). Defaults to 100. To see the largest, write topk(10, ...) into the query instead of raising this. | |
| query | Yes | A PromQL expression, e.g. `sum by (namespace) (rate(http_requests_total{status=~"5.."}[5m]))`. Aggregate inside the expression (sum by, topk, count) rather than fetching raw series and reading them: Prometheus does the arithmetic exactly and the answer is a fraction of the size. | |
| precision | No | Significant digits to round fractional values to (whole numbers are never rounded). Defaults to 4; 0 returns the exact value. Raise it only when comparing values that differ past the fourth digit. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, but the description adds important behavior beyond them: shared labels are collapsed into common_labels, upstream ordering is preserved for sort_desc()/topk(), and exceeding limit truncates results and sets truncated. These are concrete output and truncation semantics that help an agent interpret results correctly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then routes to the alternative, then explains result ordering and truncation. Every sentence carries operational value with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex query tool with no output schema, the description covers the key return behaviors including common_labels, ordering, and truncation. It does not fully describe the result object shape or error behavior, but it is sufficient for an agent to invoke and interpret the main output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents query, time, limit, and precision thoroughly, including examples and the topk() guidance. The description reinforces query shape and limit truncation but does not add syntax or constraints for time or precision beyond the schema, so it remains at the baseline for fully documented parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource: evaluate a PromQL expression at one instant. It also distinguishes this tool from prometheus_query_range and gives concrete window examples such as increase(x[24h]), so an agent can identify the operation without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says this is the right tool for almost every question and names the precise condition for using the range alternative: when the shape over time matters. That is direct when-to-use and when-not-to-use guidance against a real sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Evaluate a PromQL expression over a time range, for how something changed: a spike, a trend, when it started. Each series comes back with stats (min, max, avg, last) and, with view=values, one value per step on a shared grid given by start and step (null where there was no sample) — no per-point timestamps. The step is picked for about 60 points unless given. Many series are expensive: aggregate in the query (sum by), or use view=stats with sort=max to find the outliers first.
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | Range end: now, now-1h, -30m, an RFC3339 timestamp (2026-01-31T12:00:00Z) or unix seconds. Defaults to now. | |
| sort | No | Order of series, applied before `limit` cuts: labels keeps Prometheus's order; max/avg/last rank highest first, so a cut keeps the biggest. | labels |
| step | No | Resolution, as a duration (30s, 5m, 1h) or seconds. Defaults to a round step giving about 60 points. Each series costs one value per step. | |
| view | No | values: stats plus the value at every step. stats: min/max/avg/last only, about a tenth of the size — use it to survey many series before plotting a few. | values |
| limit | No | Maximum series to return (1-500). Defaults to 20. | |
| query | Yes | A PromQL expression, e.g. `sum by (namespace) (rate(http_requests_total{status=~"5.."}[5m]))`. Aggregate inside the expression (sum by, topk, count) rather than fetching raw series and reading them: Prometheus does the arithmetic exactly and the answer is a fraction of the size. | |
| start | No | Range start: now, now-1h, -30m, an RFC3339 timestamp (2026-01-31T12:00:00Z) or unix seconds. Defaults to now-1h. | |
| precision | No | Significant digits to round fractional values to (whole numbers are never rounded). Defaults to 4; 0 returns the exact value. Raise it only when comparing values that differ past the fourth digit. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover read-only and open-world, so the description carries the rest and does: it discloses the return shape (per-series min/max/avg/last stats, values on a shared grid, nulls for missing samples, no per-point timestamps) and the default resolution behavior (~60 points). It also flags a real operational trait — many series are expensive and per-step cost scales — which annotations cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with purpose and return shape before cost guidance. Slight redundancy with the schema — the sum by example and the view=stats/sort=max tip restate parameter descriptions — but every sentence carries actionable content and none is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters, no output schema, and only read-only/open-world annotations, the description fills exactly the gaps that matter: what comes back, how resolution is defaulted, and how to control result size. An agent can pick arguments and anticipate the response without opening anything else.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so 3 is the baseline; the description earns above that by explaining the interaction between step and point count, why sort=max pairs with view=stats to find outliers, and why to aggregate inside the query. It repeats some schema text (view values vs stats, sum by) but adds causal reasoning the schema lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Evaluate a PromQL expression over a time range") and immediately qualifies the scope with the kind of question it answers (spike, trend, when it started). The phrase "over a time range" plus the shared-grid return shape cleanly separates it from an instant-query sibling without needing to name it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete when-to-use framing ("for how something changed: a spike, a trend, when it started") and in-tool routing between view=values and view=stats, plus advice to aggregate before fetching. It never names an alternative tool such as an instant query or list_metrics, so the sibling routing is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Escape hatch: GET any /api/v1 endpoint the other tools do not wrap — /api/v1/query_exemplars, /api/v1/targets/metadata, /api/v1/alertmanagers, /api/v1/format_query, /api/v1/status/walreplay. The answer is the raw data of the envelope, unshaped, cut at max_chars. Read-only: only GET is ever sent. Prefer the named tools, which shape their output; this one can return megabytes.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | API path, starting with /api/v1/, e.g. "/api/v1/format_query". | |
| params | No | Query parameters. A repeated parameter is an array: {"match[]": ["up", "process_start_time_seconds"]}. | |
| max_chars | No | Cut the serialized answer at this many characters (100-200000). Defaults to 20000. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, it discloses that only GET is sent, that the response is the raw unshaped data field, that output is truncated at max_chars, and that it can return megabytes. These are exactly the behavioral traits an agent needs for an open-world escape-hatch tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the escape-hatch purpose, followed by examples, scope, safety, and truncation caveats. Every sentence contributes useful information without repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an open-world raw-API tool with a rich schema, the description covers purpose, alternatives, safety, and truncation well. It does not mention error-envelope or non-2xx behavior, which is a minor remaining gap for an arbitrary-endpoint tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with path pattern, params repetition semantics, and max_chars range already documented in the schema. The description reinforces max_chars truncation but does not add new parameter meaning beyond the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: GET any /api/v1 endpoint not covered by the named tools. It explicitly distinguishes itself from siblings by positioning itself as the escape hatch and naming examples of endpoints it handles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use guidance ('other tools do not wrap') and when-not-to-use guidance ('Prefer the named tools'), naming the alternative category directly. An agent can decide between this and the specific Prometheus tools without inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0prometheus_auth_statusprometheus_describe_metricprometheus_get_tsdb_statusprometheus_list_alertsprometheus_list_label_valuesprometheus_list_labelsprometheus_list_metricsprometheus_list_rulesprometheus_list_targetsprometheus_queryprometheus_query_rangeprometheus_requestScored across 12 tools
Each tool targets a distinct resource or action: instant vs. range queries are explicitly contrasted, and list_labels / list_label_values / describe_metric are differentiated with cross-references (e.g. 'describe_metric is more useful' for one metric's labels). The only potential overlap, prometheus_request, is explicitly framed as a read-only escape hatch with guidance to prefer the named tools.
All names share the prometheus_ snake_case prefix and are mostly verb_noun (query, query_range, list_metrics, describe_metric, get_tsdb_status). Minor deviations are auth_status (noun phrase) and request (bare verb), but the set remains predictable and readable.
Twelve tools is well within a healthy range and each earns its place: query, discovery, alerts/rules, target health, TSDB cardinality, and a raw escape hatch. No tool appears redundant with another.
The read-only Prometheus surface is broadly covered: queries, metric/label discovery, alerts, rules, targets, TSDB status, and auth/version checks. A dedicated series-lookup tool (/api/v1/series) and explicit config/flags endpoints are absent, but the request escape hatch lets agents work around these gaps.
Read-only access to a Lumin project's logs, metrics, uptime checks, alerts and infrastructure.
Read-only access to your Infrly services, deploys, logs, metrics and billing.
Provides read access to your GKE and Kubernetes resources.
Read-only MCP access to sessions, funnels, campaigns, errors, live visitors, and anomalies.
