MCP servers as a tool source, prometheus-mcp first #2005

Closed
opened 2026-11-14 16:02:45 +00:00 by sam · 2 comments
Owner

An investigation needs the trend, not just a snapshot: how fast a filesystem is filling and when it will be full. Prometheus has an official MCP server (prometheus/prometheus-mcp), so Archie runs it as published instead of wrapping it: core becomes an MCP client, and an MCP server is a fourth kind of accepted package beside connectors, secret engines and guards. Spec: R36. Design: ARCHITECTURE 2.5.

Requirements

Accepting a server

  1. An MCP server is accepted through the API like an extension, by name, with one of two transports:
    • stdio: a binary path and digest, launched inside the same confinement as extensions (own user and network namespaces, egress allow-list, accepted environment only), with its arguments and settings;
    • HTTP: an endpoint URL, reached through declared egress.
  2. Credential slots resolve from the credential store into the server's environment (stdio) or request headers (HTTP). One server's credentials never reach another.
  3. Acceptance carries an allow-list. Each permitted tool is declared as a lookup, or as an action with its effect. A tool the server lists but the allow-list doesn't name is never offered to the agent.
  4. A server that fails to start, exits or stops answering is reported by readiness and restarted with backoff, like an extension.

Using its tools
5. Declared tools are offered to agents beside connector lookups and actions, named so they can't collide with them, with the server's input schema. They take the same path: lookups run directly, and once judgement exists an action is judged before it runs.
6. A tool call's result and errors come back to the agent verbatim. An error result fails that tool call, not the run.
7. Tool calls carry a deadline, and results are capped in size.

Prometheus first
8. prometheus-mcp is accepted on staging over stdio with an allow-list of read tools only: query, range_query, series, label_names, label_values, metric_metadata. Its management and TSDB admin tools are not declared.
9. Prometheus computes forecasts, not the model: the investigate prompt says to use predict_linear through query for a time-until-full figure.

The old core MCP tool path moved to #2012, with the gateway and daemon that
still read it.

Done when

  • The demo's disk alert produces an investigation whose findings include a time-until-full forecast from a predict_linear query, and the figure matches the same query run by hand in Prometheus.
  • An undeclared tool, such as reload, is absent from the tools the agent is offered.
  • A stopped server shows in readiness, and a failed tool call doesn't fail the run.
An investigation needs the trend, not just a snapshot: how fast a filesystem is filling and when it will be full. Prometheus has an official MCP server (`prometheus/prometheus-mcp`), so Archie runs it as published instead of wrapping it: core becomes an MCP client, and an MCP server is a fourth kind of accepted package beside connectors, secret engines and guards. Spec: R36. Design: ARCHITECTURE 2.5. ## Requirements **Accepting a server** 1. An MCP server is accepted through the API like an extension, by name, with one of two transports: - stdio: a binary path and digest, launched inside the same confinement as extensions (own user and network namespaces, egress allow-list, accepted environment only), with its arguments and settings; - HTTP: an endpoint URL, reached through declared egress. 2. Credential slots resolve from the credential store into the server's environment (stdio) or request headers (HTTP). One server's credentials never reach another. 3. Acceptance carries an allow-list. Each permitted tool is declared as a lookup, or as an action with its effect. A tool the server lists but the allow-list doesn't name is never offered to the agent. 4. A server that fails to start, exits or stops answering is reported by readiness and restarted with backoff, like an extension. **Using its tools** 5. Declared tools are offered to agents beside connector lookups and actions, named so they can't collide with them, with the server's input schema. They take the same path: lookups run directly, and once judgement exists an action is judged before it runs. 6. A tool call's result and errors come back to the agent verbatim. An error result fails that tool call, not the run. 7. Tool calls carry a deadline, and results are capped in size. **Prometheus first** 8. `prometheus-mcp` is accepted on staging over stdio with an allow-list of read tools only: `query`, `range_query`, `series`, `label_names`, `label_values`, `metric_metadata`. Its management and TSDB admin tools are not declared. 9. Prometheus computes forecasts, not the model: the investigate prompt says to use `predict_linear` through `query` for a time-until-full figure. The old core MCP tool path moved to #2012, with the gateway and daemon that still read it. ## Done when - The demo's disk alert produces an investigation whose findings include a time-until-full forecast from a `predict_linear` query, and the figure matches the same query run by hand in Prometheus. - An undeclared tool, such as `reload`, is absent from the tools the agent is offered. - A stopped server shows in readiness, and a failed tool call doesn't fail the run.
sam added the taskmedium labels 2026-11-14 16:02:45 +00:00
sam added a new dependency 2026-11-14 16:02:46 +00:00
sam changed title from Prometheus lookup for forecasts to Prometheus connector: metric lookups and a filesystem forecast 2026-11-15 12:12:38 +00:00
sam changed title from Prometheus connector: metric lookups and a filesystem forecast to MCP servers as a tool source, prometheus-mcp first 2026-11-15 12:22:34 +00:00
Author
Owner

Accepted on staging and verified end to end.

Deployed. main at the commit that made the MCP client, plus the fixes below, deployed to the staging host; migrations 00005 and 00006 applied. prometheus-mcp v0.18.0 (linux/amd64, sha256 ea823027c6540d2adb46b6b58189e9ba8cf3b797e9a1e0043ab91d050645ceb3) sits in the host's extensions directory and is accepted over stdio:

PUT /api/mcp-servers/prometheus
{"path": "<extensions>/prometheus-mcp", "sha256": "ea8230…",
 "args": ["--prometheus.url=<the demo Prometheus>"], "egress": ["<the demo Prometheus>"],
 "tools": [query, range_query, series, label_names, label_values, metric_metadata]}

Allow-list. A run's agent-tools step pinned 9 read-only tools: the host connector's three and the six declared Prometheus tools. reload, quit, tsdb_stats and the rest are absent, and calling one by name is refused.

Forecast. An alert posted through Alertmanager, carrying instance and mountpoint. The run measured the filesystem with the host connector, then called prometheus_query with

-predict_linear(node_filesystem_avail_bytes{instance="…",mountpoint="…"}[6h],0) / deriv(node_filesystem_avail_bytes{instance="…",mountpoint="…"}[6h]) / 3600

and got 134.64637685173412. The same query run by hand against the demo Prometheus at the run's own evaluation timestamp returns 134.64637685173412. The findings report "not full for approximately 134.6 hours", and the message reached the composer.

Readiness and restart. A second accepted server pointed at a closed port made /readyz report it, with retries backing off 1s, 2s, 4s, 8s, 16s. Killing the Prometheus server's process got it restarted and its tools still answered; the reconnect is immediate, so a successful restart barely shows in readiness.

Tool errors. A server's error result comes back as its own text and fails only that call (connector test, plus the loop's in-band tool error). Not shown end to end on staging: the model didn't produce a failing call, and an empty result is an answer, not an error.

Fixes this needed, all on main before it would run: the dashboard's SPA fallback panicked against its /api/ catch-all, which took staging down on that deploy; the runtime role was granted DML on tables but not on sequences, so the deliveries insert failed every run; and a run's NULL result or a step's NULL output couldn't be read, so the trail API answered 500 for exactly the runs that failed.

Requirement 10 moved to #2012, with the gateway and daemon it depends on.

Accepted on staging and verified end to end. **Deployed.** `main` at the commit that made the MCP client, plus the fixes below, deployed to the staging host; migrations 00005 and 00006 applied. `prometheus-mcp` v0.18.0 (linux/amd64, sha256 `ea823027c6540d2adb46b6b58189e9ba8cf3b797e9a1e0043ab91d050645ceb3`) sits in the host's extensions directory and is accepted over stdio: ``` PUT /api/mcp-servers/prometheus {"path": "<extensions>/prometheus-mcp", "sha256": "ea8230…", "args": ["--prometheus.url=<the demo Prometheus>"], "egress": ["<the demo Prometheus>"], "tools": [query, range_query, series, label_names, label_values, metric_metadata]} ``` **Allow-list.** A run's `agent-tools` step pinned 9 read-only tools: the host connector's three and the six declared Prometheus tools. `reload`, `quit`, `tsdb_stats` and the rest are absent, and calling one by name is refused. **Forecast.** An alert posted through Alertmanager, carrying `instance` and `mountpoint`. The run measured the filesystem with the host connector, then called `prometheus_query` with `-predict_linear(node_filesystem_avail_bytes{instance="…",mountpoint="…"}[6h],0) / deriv(node_filesystem_avail_bytes{instance="…",mountpoint="…"}[6h]) / 3600` and got 134.64637685173412. The same query run by hand against the demo Prometheus at the run's own evaluation timestamp returns 134.64637685173412. The findings report "not full for approximately 134.6 hours", and the message reached the composer. **Readiness and restart.** A second accepted server pointed at a closed port made `/readyz` report it, with retries backing off 1s, 2s, 4s, 8s, 16s. Killing the Prometheus server's process got it restarted and its tools still answered; the reconnect is immediate, so a successful restart barely shows in readiness. **Tool errors.** A server's error result comes back as its own text and fails only that call (connector test, plus the loop's in-band tool error). Not shown end to end on staging: the model didn't produce a failing call, and an empty result is an answer, not an error. **Fixes this needed**, all on main before it would run: the dashboard's SPA fallback panicked against its `/api/` catch-all, which took staging down on that deploy; the runtime role was granted DML on tables but not on sequences, so the deliveries insert failed every run; and a run's NULL result or a step's NULL output couldn't be read, so the trail API answered 500 for exactly the runs that failed. Requirement 10 moved to #2012, with the gateway and daemon it depends on.
sam closed this issue 2026-11-15 13:24:50 +00:00
Author
Owner

Found a real gap: ARCHITECTURE.md 2.5 carries the design, but this issue's requirements had no home in SPEC.md. Its 'Spec: R36' line predates R36 becoming the Prometheus lookup, so R36 no longer described the MCP server. SPEC.md now has R46 restating the seven requirements here (accepted by name, stdio or HTTP, confined with declared egress, per-server credentials, allow-listed tools declared as lookups or actions, readiness and restart, tools offered beside connector lookups), with R36 kept as the Prometheus lookup and this issue named as the detail. The parity ledger has a row for MCP servers as an accepted package.

Found a real gap: ARCHITECTURE.md 2.5 carries the design, but this issue's requirements had no home in SPEC.md. Its 'Spec: R36' line predates R36 becoming the Prometheus lookup, so R36 no longer described the MCP server. SPEC.md now has R46 restating the seven requirements here (accepted by name, stdio or HTTP, confined with declared egress, per-server credentials, allow-listed tools declared as lookups or actions, readiness and restart, tools offered beside connector lookups), with R36 kept as the Prometheus lookup and this issue named as the detail. The parity ledger has a row for MCP servers as an accepted package.
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Reference: sam/archie#2005