Concepts

Architecture

One self-hosted binary sits between Alertmanager and your AI agent, and turns raw alerts into context worth investigating.

Phase: Ingest

Webhook Transmission

Alertmanager fires a POST to the AlertINT webhook receiver over HTTP(S). The payload is the standard Alertmanager webhook JSON — no custom format required.

Component:Alertmanager → AlertINT webhook receiver

Protocol:HTTP POST · Alertmanager webhook v2

Auth:Bearer token (ALERTINT_WEBHOOK_TOKEN)

Data Persistence & Deduplication

Received alerts are written to local state (SQLite by default). Duplicate firings of the same alert fingerprint within the dedup window are collapsed — one record per logical alert.

Component:AlertINT ingest pipeline

Storage:Local SQLite (configurable path)

Dedup key:Alertmanager alert fingerprint

Correlation Engine

Alerts that fire within a configurable time window and share common label dimensions (alertname, cluster, namespace, service) are grouped into a single incident record. Grouping is deterministic and re-evaluated as new alerts arrive.

Component:AlertINT correlation engine

Grouping keys:alertname · cluster · namespace · service

Window:Configurable — default 90 s

AI Synthesis

When the correlation window closes, AlertINT sends the grouped alert payloads to the configured LLM (Anthropic Claude). The model returns a structured finding: probable cause, severity assessment, and suggested next checks. The finding is stored locally alongside the incident.

Component:AlertINT AI worker

Model:Anthropic Claude (claude-sonnet-5 default; claude-haiku-4-5 lower-cost option)

Auth:ANTHROPIC_API_KEY env var

Output:Structured finding · stored in local state

Outbound Notification

The AI finding is posted to the configured Slack channel via the Bot Token API. When all alerts recover, AlertINT updates the original message in-place (🔴 → ✅) and posts a short resolution note in the thread. stdout is always available as a fallback.

Component:AlertINT notifier

Method:Slack Bot Token API (chat.postMessage / chat.update)

Auth:SLACK_BOT_TOKEN env var

Fallback:stdout when Slack is not configured

Phase: Investigate

Agent Entry via MCP

An engineer opens their MCP-capable AI client (Claude Code, Cursor, Windsurf, or any MCP-compatible tool). The client is pointed at the AlertINT MCP server endpoint, which runs as part of the same binary. No separate daemon is needed.

Component:AlertINT MCP server

Protocol:Model Context Protocol (MCP)

Clients:Claude Code · Cursor · Windsurf · any MCP client

Transport:Streamable HTTP (http://host:9912/mcp)

Evidence Query

The agent calls AlertINT MCP tools to list recent incidents, retrieve alert payloads, and read the stored AI finding. All data is served from local state — no external calls at this stage.

MCP tools:alertint_list_incidents · alertint_get_incident · alertint_search_alerts · alertint_get_evidence_pack

Data source:Local AlertINT state (read-only)

Writes:None

Telemetry Context

The agent issues read-only PromQL queries through AlertINT MCP tools. AlertINT proxies the query to the configured Prometheus instance and returns the result. The agent can inspect CPU, memory, latency, error rate, or any metric stored in Prometheus — scoped to the incident time window.

MCP tools:prometheus_query · prometheus_query_range

Backend:Prometheus HTTP API (read-only)

Auth:PROMETHEUS_BEARER_TOKEN env var (optional)

Writes:None — PromQL is read-only

Decision Point

The agent synthesizes alert payloads, the stored AI finding, and live metric context into a response. The engineer decides the next action — re-query, escalate, or begin remediation — with full context already in the conversation.

Actor:Engineer + AI agent

AlertINT role:Context provider only

Next step:Engineer-controlled

Ready to Remediate

The engineer acts with full incident context — alert history, correlated findings, and live metrics — all sourced read-only from within the local runtime.

MCP-first investigation

An MCP server is the primary way you and your agent interact with AlertINT.

List recent AlertINT incidents.
Open the latest critical incident and summarize the evidence.
Show the alert labels and annotations for this incident.
Query Prometheus for CPU and memory around the incident window.
Compare the finding with the metric trend and suggest next checks.