incidentrelay-mcp

Un servidor MCP para IncidentRelay: programación de guardias autohospedada, enrutamiento de alertas y gestión de incidentes.

Expone la API REST completa (279 operaciones) de IncidentRelay a los clientes MCP (Claude Desktop, Claude Code, Cursor, …) a través de dos capas:

• 3 herramientas de pasarela que hacen que todas las operaciones sean accesibles, guiadas por el documento OpenAPI del propio servidor.

• 25 herramientas seleccionadas que envuelven los flujos de trabajo habituales de guardia (reconocer/ resolver alertas, incidentes, programación de guardias, silencios, ventanas de mantenimiento) con entradas tipadas y ergonómicas.

El servidor nunca modifica IncidentRelay. Es un cliente REST puro que se autentica con un token Bearer que tú proporcionas.

Ejecución

No es necesario instalar nada: ejecútalo con npx (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 compila el paquete automáticamente en la primera ejecución (un script prepare compila TypeScript), por lo que no se necesita un paso de compilación aparte.

Desde el código fuente

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

Configuración

El servidor necesita la URL base de IncidentRelay y un token Bearer (un token de acceso JWT o un token de API personal creado en IncidentRelay en Perfil → Tokens de API, con los alcances que quieras permitir).

¹ El token solo es opcional si nunca llamas a operaciones de escritura.

Al iniciar, el servidor obtiene {IR_BASE_URL}/api/openapi.json (un endpoint público) para construir su catálogo de operaciones, por lo que siempre coincide con la versión de IncidentRelay desplegada. Si esa descarga falla, recurre a una instantánea incluida y registra una advertencia.

Uso con Claude Desktop / Claude Code (stdio)

Añádelo a la configuración de tu cliente MCP (p. ej. claude_desktop_config.json).

Recomendado: ejecuta directamente el binario precompilado (arranca en <0.5s, por lo que nunca supera el tiempo de espera de inicio del cliente):

{
  "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>"
      }
    }
  }
}

Compílalo una vez con npm install && npm run build (o npm install -g .).

Alternativa: npx. Una vez publicado en npm:

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

⚠️ Evita npx -y github:… en la configuración de un cliente: su primera ejecución clona el repositorio, instala dependencias y compila TypeScript, lo que puede superar el tiempo de conexión de ~30s de un cliente MCP con caché fría. Usa el binario precompilado (o la forma npm después de publicarlo) para un cliente que lanza el servidor bajo demanda.

El servidor en sí se inicia al instante independientemente de la red: carga una instantánea OpenAPI incluida de forma síncrona y, a continuación, actualiza el catálogo desde el servidor en vivo en segundo plano.

Uso a través de 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

El transporte HTTP es sin estado (un servidor por solicitud), se enlaza a 127.0.0.1 por defecto y tiene habilitada la protección contra el reenlace de DNS.

Herramientas

Pasarela (cubre las 279 operaciones)

Flujo típico: ir_list_operations → ir_describe_operation → ir_call.

Seleccionadas (flujos de trabajo habituales de guardia)

Alertas: ir_list_alerts, ir_get_alert, ir_ack_alert, ir_resolve_alert, ir_comment_alert · Incidentes: ir_list_incidents, ir_get_incident, ir_create_incident, ir_add_incident_responder, ir_set_incident_priority · Guardia: ir_who_is_on_call, ir_oncall_health, ir_list_rotations, ir_create_rotation_override · Silencios: ir_list_silences, ir_create_silence, ir_remove_silence · Mantenimiento: ir_list_maintenance_windows, ir_create_maintenance_window · Contexto: ir_list_teams, ir_list_routes, ir_list_channels, ir_whoami · Heartbeats: ir_list_heartbeats, ir_send_heartbeat.

Uso seguro

• Confirm-guard. Las operaciones destructivas (DELETE, y las rutas con disable/remove/delete/reset/regenerate-token/intake-token/ cancel/merge/revoke) no se ejecutan a menos que pases confirm: true. Sin ello, la herramienta devuelve una vista previa de ejecución en seco.

• Modo de solo lectura. Establece IR_READONLY=true para rechazar cualquier operación que no sea GET en la capa de herramientas.

• Eliminación de tokens. Los tokens Bearer se eliminan de los registros y de las salidas de error.

Seguridad

IR_VERIFY_TLS=false desactiva la verificación del certificado TLS en las llamadas salientes hacia IncidentRelay. Esto expone el tráfico a ataques de intermediario (man-in-the-middle) y debería usarse solo en una red de confianza. Para certificados autofirmados en instalaciones propias, es preferible añadir la CA del servidor a tu almacén de confianza (o usar un certificado emitido correctamente) en lugar de desactivar la verificación. Cuando está desactivada, el servidor imprime una advertencia al iniciar.

Desarrollo

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

Para regenerar la instantánea OpenAPI incluida, consulta scripts/generate-snapshot.md.

Diseño y plan

• Especificación de diseño: docs/superpowers/specs/2026-08-17-incidentrelay-mcp-design.md

• Plan de implementación: docs/superpowers/plans/2026-08-17-incidentrelay-mcp.md