MCP clients

Your AI agent connects to AlertINT over MCP to read Situations, query your telemetry, and record your verdicts.

Endpoint	http://<host>:9912/mcp (Streamable HTTP, inside alertint serve)
Auth	Authorization: Bearer <token>, the value of ALERTINT_MCP_TOKEN
On/off	On when the token variable is set; mcp.enabled: false forces it off
Ready-made configs	examples/mcp-clients/ in the repo

The token is shared by the whole team. Every client presents the same value, so keep it where teammates can find it.

• Any long random string works (compared byte for byte).
• On Kubernetes, read it back from the Secret: kubectl get secret <name> -o jsonpath='{.data.ALERTINT_MCP_TOKEN}' | base64 -d
• Lost it? Set a new value, restart the agent, and update every client.

AlertINT on another machine? Replace http://localhost:9912/mcp below with its address, over HTTPS.

Client	Setup
Claude Code	One claude mcp add command
Codex	One codex mcp add command, shared by the CLI, IDE extension, and app
Gemini CLI	One gemini mcp add command
Cursor	~/.cursor/mcp.json
VS Code (GitHub Copilot)	.vscode/mcp.json, which prompts for the token
Windsurf	~/.codeium/windsurf/mcp_config.json
Any other client	Needs Streamable HTTP and a custom Authorization header; use the endpoint and auth above

Claude Code#

export ALERTINT_MCP_TOKEN="<your-token>"
claude mcp add --transport http --scope user alertint http://localhost:9912/mcp --header "Authorization: Bearer ${ALERTINT_MCP_TOKEN}"

--scope user makes it available in every project; --scope local keeps it to the current one. Or add it to .mcp.json (project) or ~/.claude.json (global) and reload with /mcp:

{
  "mcpServers": {
    "alertint": {
      "type": "http",
      "url": "http://localhost:9912/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ALERTINT_MCP_TOKEN"
      }
    }
  }
}

Codex#

Codex stores the variable's name, not the token:

export ALERTINT_MCP_TOKEN="<your-token>"
codex mcp add alertint --url http://localhost:9912/mcp --bearer-token-env-var ALERTINT_MCP_TOKEN

Check it with codex mcp get alertint. The CLI, IDE extension, and desktop app share this config. Or add it to ~/.codex/config.toml (global) or .codex/config.toml (trusted project):

[mcp_servers.alertint]
url = "http://localhost:9912/mcp"
bearer_token_env_var = "ALERTINT_MCP_TOKEN"

Situation investigation skill#

A Codex skill that turns a Situation ID, handle, or Slack message into a short, record-backed brief. It holds no token or address; it uses the alertint connection above.

mkdir -p ~/.codex/skills
cp -R client-skills/alertint-situation-investigation ~/.codex/skills/

• Restart Codex to load it.
• Match versions: install the skill from the same release as the server.
• Remove: delete ~/.codex/skills/alertint-situation-investigation.

Gemini CLI#

export ALERTINT_MCP_TOKEN="<your-token>"
gemini mcp add --scope user --transport http --header "Authorization: Bearer ${ALERTINT_MCP_TOKEN}" alertint http://localhost:9912/mcp

--scope user writes ~/.gemini/settings.json, for every project; the default, project, writes .gemini/settings.json. Check it with /mcp list. The file holds:

{
  "mcpServers": {
    "alertint": {
      "httpUrl": "http://localhost:9912/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ALERTINT_MCP_TOKEN"
      }
    }
  }
}

Cursor#

Add to ~/.cursor/mcp.json, restart Cursor, and check Settings → MCP:

{
  "mcpServers": {
    "alertint": {
      "url": "http://localhost:9912/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ALERTINT_MCP_TOKEN"
      }
    }
  }
}

VS Code#

For GitHub Copilot agent mode. Add to .vscode/mcp.json in your workspace, or run MCP: Open User Configuration to use it in every workspace:

{
  "servers": {
    "alertint": {
      "type": "http",
      "url": "http://localhost:9912/mcp",
      "headers": {
        "Authorization": "Bearer ${input:alertint-mcp-token}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "alertint-mcp-token",
      "description": "AlertINT MCP token (ALERTINT_MCP_TOKEN)",
      "password": true
    }
  ]
}

• Token: VS Code asks for it when the server first starts. The file holds no secret, so the team can commit it.
• Check it: run MCP: List Servers.

Windsurf#

Add to ~/.codeium/windsurf/mcp_config.json, restart Windsurf, and check Settings → MCP Servers:

{
  "mcpServers": {
    "alertint": {
      "serverUrl": "http://localhost:9912/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ALERTINT_MCP_TOKEN"
      }
    }
  }
}

Tools#

Three groups, in the order an investigation uses them.

Read AlertINT state#

Read-only. Served from AlertINT's local state.

Tool	Returns
alertint_list_situations	Situations, most recently updated first: lifecycle, attention, next due time
alertint_get_situation	One Situation by ID or handle: assessment, operator contract, current judgment, episode summary, Slack delivery state
alertint_list_situation_transitions	One Situation's change history, oldest first
alertint_list_situation_judgments	One Situation's "expected" judgment history
alertint_list_observation_runs	Evidence gathered for one Situation, per check: result, coverage, facts. Detail expires after 10 days unused.
alertint_get_delivery_state	Installation-wide Slack delivery: failures, blocked messages, delivery gaps, backlog
alertint_list_incidents	Incidents, filtered by status
alertint_get_incident	One Incident: Finding, memory, and operator_history (verdict and notes)
alertint_get_evidence_pack	The evidence an Incident's triage used
alertint_search_alerts	Raw alerts by label
alertint_recent_changes	Deploys, releases, and PRs matching a label selector
alertint_get_semantic_profile	Advisory profiles for a source or Situation, with version history
alertint_get_expected_behavior	One expected schedule's current state
alertint_list_expected_behaviors	Expected schedules, filtered by group, source, or rule
alertint_list_expected_behavior_history	One schedule's revision history
alertint_get_expected_behavior_validation	A prepared schedule-proof request and its result
alertint_usage_stats	Alerts, LLM tokens, Slack posts, withheld posts, analyses, and exhausted triage over a time window
alertint_verify_audit	Checks the audit log's hash chain for tampering

Query your telemetry#

Read-only. AlertINT proxies each query to your backend, with the scope and time you give it.

Tool	Queries	Available when
prometheus_query, prometheus_query_range	PromQL, instant or range	Always listed; errors if Prometheus isn't configured
loki_query_range	Logs, in the backend's query language	A log source is enabled
sentry_issues_list	Live Sentry issues by project and status	The Sentry error source is enabled
sentry_issues_trace	Stack traces (file:line) for up to 10 issues	The Sentry error source is enabled
zabbix_metric_history	Metric history or trends for a host and item	The Zabbix API is configured
zabbix_host_problems	Open problems for a host	The Zabbix API is configured

Record your decisions#

Writes to AlertINT's own state only, never to your systems. Each write is audit-chained and needs explicit confirmation.

Tool	Records
alertint_incident_capture_verdict	A confirmation or correction of a Finding. A correction is tested on the next triage (how).
alertint_incident_annotate	A note for the next person. Shown in the Situation's thread; never enters triage.
alertint_record_situation_expected	"This Situation is expected until …" (non-critical conditions only)
alertint_replace_situation_expected	A new expected revision with a new deadline
alertint_revoke_situation_expected	Withdraws "expected"; normal assessment resumes
alertint_restore_situation_expected	Restores a withdrawn judgment against current facts
alertint_expected_behavior_prepare	Proof for a proposed reusable schedule (Zabbix or Alertmanager rule). Grants nothing by itself.
alertint_expected_behavior_confirm	Turns a confirmed judgment into a reusable expected schedule
alertint_expected_behavior_replace	Replaces a schedule
alertint_expected_behavior_revoke	Withdraws a schedule; monitoring and recovery continue
alertint_expected_behavior_restore	Restores a withdrawn schedule as a new, freshly proven revision
alertint_correct_semantic_profile	A correction to an advisory profile, as a new version

• "Expected" never stops monitoring. It lowers urgency and changes wording; recovery tracking continues.
• Writes use version checks. A stale version is refused; re-read and retry.
• No owning Situation? A verdict or note still lands and stays visible on the Incident and in the audit log.
• Tool hints (read-only, destructive, idempotent) help clients display tools. They are not access control.

Investigate a Situation#

Current state first, then history. Never reconstruct the past from today's configuration.

alertint_get_situation {"handle":"SIT-2026-0142"}
alertint_list_situation_transitions {"situation_id":"sit-0142"}
alertint_list_observation_runs {"situation_id":"sit-0142"}
alertint_get_delivery_state {}

A grounded answer separates four things:

Part	Comes from
Current state	Lifecycle, attention, source state, applicable judgment, next checkpoint
What changed	The transition or schedule-history row: what, when, who, why
Evidence	The observation or delivery record, and whether it succeeded, was empty, or was unavailable
Missing history	Say "AlertINT has no recorded history for that", never a guess

Default answer shape: Finding / Evidence / Now / Next, then up to three follow-up reads. Next is AlertINT's recorded action and deadline, not proposed operator work. With no supported Finding, say Finding: Insufficient evidence and name what's missing.

Example, for "Why did this stop being expected, and why hasn't it recovered?" (IDs and times are illustrative):

The Situation is in Monitoring. Expected schedule env-nightly-payments v3 stopped applying at 2026-09-22T22:41:08Z: transition tr-0187 records source_identity_or_version_changed, and observation run obs-0441 records the new rule version. It hasn't recovered because delivery del-9921 still shows one member firing at 2026-09-22T22:42:03Z, so recovery grace hasn't started. Slack delivery is healthy.

Check the connection#

At setup or after a failure: initialize, list tools, and run one small read such as alertint_list_situations with a low limit.

• Report separately: configured, queried successfully, failed, not checked.
• Listed isn't reachable: log, change, Sentry, and Zabbix tools appear only when configured, but that doesn't prove the backend answers. Prometheus tools are always listed.
• Don't probe every connector just to fill a health table.