opsgenie-mcp

Servidor MCP para Opsgenie (la plataforma de gestión de incidentes/alertas y guardias de Atlassian) — expone la API REST pública completa de Opsgenie como herramientas MCP.

⚠️ Nota del proveedor: Atlassian ha anunciado que Opsgenie está llegando a su fin de soporte y recomienda migrar a Jira Service Management o Compass. La API pública documentada aquí (docs.opsgenie.com) sigue activa y sin cambios a partir de esta compilación, pero se espera que eventualmente quede obsoleta.

Resumen

• Servicio HTTP sin estado. No se persisten credenciales nunca: cada solicitud proporciona su propia clave de API mediante un encabezado, utilizada solo durante la vida de esa única solicitud.

• Admite solicitudes concurrentes; el aislamiento de credenciales por solicitud se realiza mediante contextvars de Python, no con una instancia de cliente global/compartida.

• Puntos de entrada: POST /mcp (protocolo MCP) y GET /health (comprobación de salud).

• Puerto predeterminado: 8080 (configurable mediante MCP_HTTP_PORT).

Related MCP server: MCP Setup Server

Alcance

22 herramientas, reducidas de una compilación original de 213 herramientas de API completa (2026-08-04), todas en la única categoría alert. La configuración de integración almacenada de MSPbots para este proveedor llama exactamente 1 endpoint (GET /v2/alerts, solo lectura, → opsgenie_alert_list_alerts). Según la decisión de alcance de "uso real + CRUD central de la misma categoría", cada otra categoría (Incident, Incident Timeline, Integration, Heartbeat, Alert & Notification Policy, Policy (legacy v1), Maintenance, Account, User, Custom User Role, Contact, Notification Rule (+ Step), Team (+ Member/Role/Routing Rule), Schedule (+ Rotation/Override), Escalation, Who Is On Call, Forwarding Rule, Service (+ Incident Rules/Templates), Incident Templates — 27 categorías, ~178 herramientas) se eliminó por completo, ya que MSPbots no toca ninguna de ellas; dentro de la propia categoría alert, 35 herramientas originales se redujeron a las 22 operaciones centrales del ciclo de vida de alertas (list/get/create/close/delete/acknowledge/unacknowledge/note/tags/assign/responder/team/escalate/snooze/update message-description-priority/count/logs/request-status) — se eliminaron la subcaracterística de búsqueda guardada (5 herramientas), la subcaracterística de adjuntos (4 herramientas), agregar/eliminar propiedades personalizadas (2 herramientas), execute_custom_action (1) y list_alert_recipients (1), ninguna de las cuales es CRUD central de alertas.

Los datos de origen de las herramientas conservadas se extrajeron originalmente obteniendo docs.opsgenie.com/docs/alert-api y estructurando cada operación documentada (método, ruta, parámetros de ruta/consulta, campos del cuerpo JSON) en un formato legible por máquina: el mismo enfoque de generación de código a partir de especificaciones estructuradas utilizado para otros proveedores de API grandes en este programa (ConnectSecure, Dynu, Jira Data Center), adaptado aquí porque Opsgenie no tiene una especificación OpenAPI/Postman descargable, solo documentación en prosa. Si se necesita una categoría eliminada más adelante, las mismas páginas de origen (docs.opsgenie.com/docs/*-api) se pueden volver a analizar de la misma manera.

Autenticación

Opsgenie utiliza una clave de API estática vinculada a una integración específica de Opsgenie (creada en Configuración → Integraciones → API de Opsgenie). La convención de integración propia de MSPbots envía esta clave como Authorization: GenieKey <apiKey>, coincidiendo con el formato documentado de Opsgenie, y este servidor la reenvía exactamente de esa manera.

Descripción de parámetros de autorización del encabezado

Si falta el encabezado requerido, se devuelve 401:

{
  "error": "Missing credentials",
  "message": "This server requires the X-Opsgenie-Api-Key header",
  "required_headers": ["X-Opsgenie-Api-Key"],
  "optional_headers": ["X-Opsgenie-Base-Url"]
}

Variables de entorno

Endpoint MCP

• POST /mcp — protocolo MCP (transporte HTTP transmisible)

• GET /health — comprobación de salud, devuelve {"status": "ok"} (sonda de actividad local pura, no llama a Opsgenie)

Lista de herramientas

Los nombres de las herramientas son opsgenie_<category>_<operation>, derivados del encabezado de cada operación en la documentación oficial (por ejemplo, "List Alerts" en la categoría alert → opsgenie_alert_list_alerts). Los parámetros body se aceptan como un dict genérico: la lista exacta de campos para cada uno está documentada en el docstring de esa herramienta (extraído de la documentación de origen), y el esquema completo de campos está disponible en la referencia de la API de Opsgenie (enlazada a continuación).

Ejemplo de prueba

# Health check
curl -s http://localhost:8080/health

# Call a tool via the MCP protocol (streamable HTTP) — requires an
# initialize handshake first per the MCP spec; abbreviated example below
# shows the tool-call request body only:
curl -s -X POST http://localhost:8080/mcp \
  -H "X-Opsgenie-Api-Key: <your-opsgenie-api-key>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "opsgenie_alert_list_alerts",
      "arguments": {"limit": 5}
    }
  }'

Verificado en vivo (2026-07-30): se llamó a opsgenie_alert_list_alerts (el mismo endpoint que MSPbots utiliza) de extremo a extremo a través de este servidor en ejecución con una clave de API de prueba real y devolvió datos reales de alertas (mensaje, estado, prioridad, respondedores, integración, etc.) de la cuenta. También se llamaron otras dos herramientas de categorías diferentes (opsgenie_team_list_teams, opsgenie_account_get_account_info) con la misma clave y devolvieron correctamente el 403 API Key is not granted with configuration access de Opsgenie, lo que confirma que la canalización de solicitudes/cabeceras de autenticación funciona correctamente también fuera de la categoría alert; esta clave de prueba específica solo tiene acceso a nivel de alertas (una restricción normal de clave de integración de Opsgenie, no un error).

Referencia de la API

• Descripción general: https://docs.opsgenie.com/docs/api-overview

• Autenticación: https://docs.opsgenie.com/docs/authentication

• La documentación por categorías está enlazada desde la barra lateral en https://docs.opsgenie.com/docs/alert-api

Brechas conocidas

• Reducido de 213 a 22 herramientas el 2026-08-04. La compilación original cubría la API pública completa en 28 categorías según una decisión de alcance anterior. Una decisión de alcance posterior lo recortó a la categoría realmente utilizada por MSPbots (alert) más su CRUD básico; consulte la sección de Alcance anterior para ver exactamente qué se mantuvo/eliminó dentro de alert y la lista completa de las 27 categorías eliminadas (~178 herramientas). Si se necesita una categoría eliminada más adelante, las mismas páginas docs.opsgenie.com/docs/*-api se pueden volver a analizar de la misma manera en que se generaron las herramientas conservadas.

• Varias herramientas conservadas aún mutan el estado real de las alertas de Opsgenie (opsgenie_alert_delete_alert, opsgenie_alert_close_alert, opsgenie_alert_create_alert, etc.); trátelas como irreversibles/cambiantes de estado y confirme con una persona antes de invocarlas.

• Los parámetros body no están tipados (dict) en lugar de estar completamente modelados: el docstring de cada herramienta enumera los nombres de campos extraídos de la documentación de Opsgenie, pero reproducirlos todos como parámetros Python tipados estaba fuera del alcance de un servidor generado mecánicamente.

• Los datos de origen se extrajeron de documentación en prosa, no de una especificación de máquina — Opsgenie no tiene una colección OpenAPI/Postman descargable, por lo que el método/ruta/parámetros de cada operación se analizó del HTML de docs.opsgenie.com.

• Solo opsgenie_alert_list_alerts (el endpoint propio de MSPbots) se verificó en vivo con datos reales devueltos. Las 21 herramientas restantes son estructuralmente correctas (esquema validado, tools/list del protocolo MCP confirmado, todas pasan compile()), pero no se probaron individualmente; varias son operaciones de escritura/destructivas que crearían, modificarían o cerrarían alertas reales, por lo que no se ejecutaron contra la cuenta de prueba en vivo.

• El proveedor está llegando al fin de soporte (consulte el banner de advertencia en la parte superior de este README) — Atlassian recomienda migrar a Jira Service Management o Compass. Este MCP apunta a la API pública de Opsgenie aún activa a partir de esta compilación.