incidentrelay-mcp

Ein MCP-Server für IncidentRelay — selbst gehostete On-Call-Planung, Alarmweiterleitung und Incident-Management.

Er stellt IncidentRelays gesamte REST-API (279 Operationen) MCP-Clients (Claude Desktop, Claude Code, Cursor, …) über zwei Ebenen bereit:

• 3 Gateway-Tools, die jede Operation erreichbar machen, gesteuert durch das OpenAPI-Dokument des Servers.

• 25 kuratierte Tools, die die gängigen On-Call-Workflows (Alarme bestätigen/auflösen, Incidents, On-Call-Plan, Stummschaltungen, Wartungsfenster) mit typisierten, ergonomischen Eingaben umschließen.

Der Server verändert IncidentRelay nie. Er ist ein reiner REST-Client, der sich mit einem von dir bereitgestellten Bearer-Token authentifiziert.

Ausführen

Keine Installation nötig — führe es mit npx aus (Node.js ≥ 20):

# from GitHub (works today)
IR_BASE_URL=https://incidentrelay.example.com IR_TOKEN=<token> \
  npx -y github:NikGariel/IncidentRelay-mcp

# from npm (after the package is published)
IR_BASE_URL=https://incidentrelay.example.com IR_TOKEN=<token> \
  npx -y incidentrelay-mcp

npx baut das Paket beim ersten Lauf automatisch (ein prepare-Skript kompiliert TypeScript), daher ist kein separater Build-Schritt erforderlich.

Aus dem Quellcode

npm install   # runs the build via the prepare script
npm start

Konfiguration

Der Server benötigt die Basis-URL von IncidentRelay und ein Bearer-Token (ein JWT-Zugriffstoken oder ein persönliches API-Token, das in IncidentRelay unter Profil → API-Tokens mit den gewünschten Berechtigungen (Scopes) erstellt wird).

¹ Das Token ist nur optional, wenn du nie Schreiboperationen aufrufst.

Beim Start ruft der Server {IR_BASE_URL}/api/openapi.json (einen öffentlichen Endpunkt) ab, um seinen Operationskatalog aufzubauen, sodass er immer mit der bereitgestellten IncidentRelay-Version übereinstimmt. Schlägt dieser Abruf fehl, fällt er auf eine gebündelte Momentaufnahme (Snapshot) zurück und protokolliert eine Warnung.

Verwendung mit Claude Desktop / Claude Code (stdio)

Füge dies zu deiner MCP-Client-Konfiguration hinzu (z. B. claude_desktop_config.json).

Empfohlen — das vorkompilierte Binary direkt ausführen (startet in weniger als 0,5 s, sodass es das Start-Timeout des Clients nie überschreitet):

{
  "mcpServers": {
    "incidentrelay": {
      "command": "node",
      "args": ["/absolute/path/to/incidentrelay-mcp/dist/index.js"],
      "env": {
        "IR_BASE_URL": "https://incidentrelay.example.com",
        "IR_TOKEN": "<personal-api-token>"
      }
    }
  }
}

Baue es einmal mit npm install && npm run build (oder npm install -g .).

Alternative — npx. Sobald es bei npm veröffentlicht ist:

{ "command": "npx", "args": ["-y", "incidentrelay-mcp"], "env": { "…": "…" } }

⚠️ Vermeide npx -y github:… in einer Client-Konfiguration: Sein erster Lauf klont das Repository, installiert Abhängigkeiten und kompiliert TypeScript, was das ~30s-Verbindungszeitlimit eines MCP-Clients bei kaltem Cache überschreiten kann. Verwende das vorkompilierte Binary (oder die npm-Form nach der Veröffentlichung) für einen Client, der den Server bei Bedarf startet.

Der Server selbst startet sofort, unabhängig vom Netzwerk: Er lädt eine gebündelte OpenAPI-Momentaufnahme synchron und aktualisiert den Katalog dann im Hintergrund vom Live-Server.

Verwendung über HTTP (Streamable HTTP)

IR_BASE_URL=https://incidentrelay.example.com IR_TOKEN=... \
  npx -y github:NikGariel/IncidentRelay-mcp --transport http --port 3000
# serves MCP at http://127.0.0.1:3000/mcp

Der HTTP-Transport ist zustandslos (ein Server pro Anfrage), bindet standardmäßig an 127.0.0.1 und hat DNS-Rebinding-Schutz aktiviert.

Tools

Gateway (deckt alle 279 Operationen ab)

Typischer Ablauf: ir_list_operations → ir_describe_operation → ir_call.

Kuratiert (gängige On-Call-Workflows)

Alarme: ir_list_alerts, ir_get_alert, ir_ack_alert, ir_resolve_alert, ir_comment_alert · Incidents: ir_list_incidents, ir_get_incident, ir_create_incident, ir_add_incident_responder, ir_set_incident_priority · On-Call: ir_who_is_on_call, ir_oncall_health, ir_list_rotations, ir_create_rotation_override · Stummschaltungen: ir_list_silences, ir_create_silence, ir_remove_silence · Wartung: ir_list_maintenance_windows, ir_create_maintenance_window · Kontext: ir_list_teams, ir_list_routes, ir_list_channels, ir_whoami · Heartbeats: ir_list_heartbeats, ir_send_heartbeat.

Sicherheitsvorkehrungen

• Confirm-guard. Destruktive Operationen (DELETE und Pfade mit disable/remove/delete/reset/regenerate-token/intake-token/cancel/merge/revoke) werden nicht ausgeführt, außer du übergibst confirm: true. Ohne dies gibt das Tool eine Trockenlauf-Vorschau (Dry-Run) zurück.

• Nur-Lese-Modus. Setze IR_READONLY=true, um jede Nicht-GET-Operation auf der Tool-Ebene abzulehnen.

• Token-Schwärzung. Bearer-Tokens werden aus Logs und Fehlerausgaben entfernt.

Sicherheit

IR_VERIFY_TLS=false deaktiviert die TLS-Zertifikatsverifizierung bei ausgehenden Aufrufen an IncidentRelay. Dies setzt den Datenverkehr Man-in-the-Middle-Angriffen aus und sollte nur in einem vertrauenswürdigen Netzwerk verwendet werden. Bei selbst gehosteten, selbstsignierten Zertifikaten bevorzuge das Hinzufügen der CA des Servers zu deinem Vertrauensspeicher (oder verwende ein ordnungsgemäß ausgestelltes Zertifikat), anstatt die Verifizierung zu deaktivieren. Wenn deaktiviert, gibt der Server beim Start eine Warnung aus.

Entwicklung

npm test          # run the vitest suite
npm run dev       # run from source with tsx
npm run build     # typecheck + emit dist/ + copy the OpenAPI snapshot

Regenerierung der gebündelten OpenAPI-Momentaufnahme: siehe scripts/generate-snapshot.md.

Design & Plan

• Design-Spezifikation: docs/superpowers/specs/2026-08-17-incidentrelay-mcp-design.md

• Implementierungsplan: docs/superpowers/plans/2026-08-17-incidentrelay-mcp.md