How do I use the Codex CLI to investigate alerts from Prometheus with Tares?

Tares lets the Codex CLI investigate Prometheus alerts over MCP. You add one MCP server to Codex, then ask about the service that alerted. Codex answers from a single correlated timeline that holds the alert and the logs, metrics and findings around it. The prometheus_alerts source feeds the alerts in, and you do not need Alertmanager or PromQL.

How it works

Two pieces work together.

• The alerts come in through the prometheus_alerts source. Tares polls Prometheus’s /api/v1/alerts every 30 seconds by default. Each active alert becomes one event, with event_type set to the alert name, text set to its summary, and the alert’s labels as Tares labels. Each event also carries a state label of firing, pending or resolved. Tares tracks state across polls, so an alert fires once and emits a resolved event when it clears. See Prometheus alerts for every field.
• Codex reads through the Tares MCP server. Codex discovers the Tares tools and calls read with a label selector such as service set to api-server. It gets a time-ordered timeline across every source that carries that label. When your metrics, logs and alerts share the same service label, the alert shows up next to the error logs and the metric that tripped it, on one clock.

Prometheus keeps deciding what counts as an alert. Tares correlates what fired with the evidence around it.

Set it up

1. Add the alerts source. In the console, go to Sources, then Add source, then Prometheus alerts, enter your Prometheus URL and click Discover. Or use this YAML:

   - name: alerts
     connector: prometheus_alerts
     poll: 30s
     config:
       url: http://localhost:9090
       severities: critical,warning   # blank = all
       labels:
         - { name: severity, field: labels.severity, primary: true }
         - { name: state, field: state }

   You can also ask a connected agent: “Use tares to ingest the firing alerts from the Prometheus at localhost:9090.”

2. Promote a shared label. Once alerts have been ingested, open the source’s Fields tab and add labels such as service or namespace. Use the same service label on your metrics and log sources, so all of them land on one timeline per service. The AI SRE guide walks through this wiring end to end.

3. Start Tares and the MCP server. The daemon alone does not serve /mcp, so run the MCP server as a second process:

   tares up
   tares mcp --transport streamable-http --port 8788 --taresd http://localhost:8787

4. Register Tares in Codex. Keep --url before the URL, because a bare URL registers a stdio server:

   codex mcp add tares --url http://localhost:8788/mcp

   For a server or Tares Cloud instance, use your own endpoint and let Codex read a read-scoped API key from an environment variable:

   export TARES_API_KEY=<api-key>
   codex mcp add tares --url https://<your-host>/mcp \
     --bearer-token-env-var TARES_API_KEY

   The Connecting agents page lists the endpoint for each place Tares can run.

5. Verify. Ask Codex: “Use tares: what are you ingesting right now?” Codex calls catalog_list and answers with your sources, triggers and projects. The console’s Reads page shows each read tagged client = mcp.

6. Investigate. Name the service that alerted:

   Use tares: what happened to api-server in the last 15 minutes? Which alerts fired, and what do the logs and metrics show around them?

   Codex calls read on that service and answers from the correlated timeline.

What you get

• Codex sees the alert and its evidence together, so it ties the failure to specific log lines and metric changes instead of starting from the alert name alone.
• You get one event per alert and a resolved event when it clears, so Codex can tell an active incident from one that has ended.
• Findings recorded in the project show up in the same read. A later question starts from the previous conclusion instead of from scratch.
• Codex can narrow a read to chosen sources with read, and look up what exists with catalog_list and catalog_describe.
• Alerting stays in Prometheus. Tares does not re-threshold anything.

When something else fits

• If your alerts already route through Alertmanager, the alertmanager connector ingests what it sends to a Tares ingest URL. Connect Codex the same way.
• If you want an agent woken the moment an alert fires, instead of asking Codex yourself, add a trigger and a Tares agent as the AI SRE guide describes. Codex then reads the result.

Related