opsgenie-mcp

MCP-сервер для Opsgenie (платформа Atlassian для управления инцидентами/оповещениями и дежурствами) — предоставляет полный публичный REST API Opsgenie в виде инструментов MCP.

⚠️ Примечание вендора: Atlassian объявила, что Opsgenie достигнет конца поддержки и рекомендует перейти на Jira Service Management или Compass. Публичный API, описанный здесь (docs.opsgenie.com), всё ещё работает и не менялся на момент этой сборки, но ожидается, что со временем он будет объявлен устаревшим.

Обзор

• Статусный HTTP-сервис. Учётные данные никогда не сохраняются — каждый запрос предоставляет свой собственный API-ключ через заголовок, который используется только в течение жизни этого единственного запроса.

• Поддерживает конкурентные запросы; изоляция учётных данных для каждого запроса выполняется через Python contextvars, а не через глобальный/общий экземпляр клиента.

• Точки входа: POST /mcp (протокол MCP) и GET /health (проверка работоспособности).

• Порт по умолчанию: 8080 (настраивается через MCP_HTTP_PORT).

Related MCP server: MCP Setup Server

Область применения

22 инструмента, сокращённых из исходной полной сборки API с 213 инструментами (2026-08-04), все в единственной категории alert. Собственная сохранённая конфигурация интеграции MSPbots для этого вендора вызывает ровно 1 конечную точку (GET /v2/alerts, только чтение, → opsgenie_alert_list_alerts). Согласно решению об области применения «фактическое использование + базовые CRUD-операции той же категории», все другие категории (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 категорий, ~178 инструментов) были полностью удалены, поскольку MSPbots их не использует; в самой категории alert 35 исходных инструментов были сокращены до 22 основных операций жизненного цикла оповещений (list/get/create/close/delete/acknowledge/unacknowledge/note/tags/assign/responder/team/escalate/snooze/update message-description-priority/count/logs/request-status) — были удалены подфункция сохранённых поисков (5 инструментов), подфункция вложений (4 инструмента), добавление/удаление пользовательских свойств (2 инструмента), execute_custom_action (1) и list_alert_recipients (1), ни одна из которых не является базовым CRUD для оповещений.

Исходные данные для сохранённых инструментов были первоначально извлечены путём получения docs.opsgenie.com/docs/alert-api и структурирования каждой документированной операции (метод, путь, параметры пути/запроса, поля JSON-тела) в машиночитаемый формат — тот же подход codegen-from-structured-spec, который используется для других крупных API-вендоров в этой программе (ConnectSecure, Dynu, Jira Data Center), адаптированный здесь, потому что у Opsgenie нет загружаемой спецификации OpenAPI/Postman, только прозаическая документация. Если позже понадобится удалённая категория, те же исходные страницы (docs.opsgenie.com/docs/*-api) можно повторно разобрать тем же способом.

Аутентификация

Opsgenie использует статический API-ключ, привязанный к конкретной интеграции Opsgenie (создаётся в Opsgenie: Settings → Integrations → API). Собственная конвенция интеграции MSPbots отправляет этот ключ как Authorization: GenieKey <apiKey>, что соответствует документированному формату Opsgenie, и этот сервер пересылает его именно так.

Параметры авторизации в заголовке

Отсутствие обязательного заголовка возвращает 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"]
}

Переменные окружения

Конечная точка MCP

• POST /mcp — протокол MCP (транспорт streamable HTTP)

• GET /health — проверка работоспособности, возвращает {"status": "ok"} (чисто локальный зонд живости, не вызывает Opsgenie)

Список инструментов

Имена инструментов имеют вид opsgenie_<категория>_<операция>, образованные от заголовка каждой операции в официальной документации (например, «List Alerts» в категории alert → opsgenie_alert_list_alerts). Параметры body принимаются как универсальный dict — точный список полей для каждого инструмента описан в его собственной docstring (извлечённой из исходной документации), а полная схема полей доступна в справочнике API Opsgenie (ссылка ниже).

Примеры тестирования

# 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}
    }
  }'

Проверено вживую (2026-07-30): opsgenie_alert_list_alerts (тот же endpoint, который вызывает сам MSPbots) был вызван сквозным образом через этот запущенный сервер с реальным тестовым API-ключом и вернул реальные данные оповещений (сообщение, статус, приоритет, ответственные, интеграция и т. д.) из аккаунта. Два других инструмента из разных категорий (opsgenie_team_list_teams, opsgenie_account_get_account_info) также были вызваны с тем же ключом и корректно вернули собственный 403 API Key is not granted with configuration access — что подтверждает, что механизм запросов/заголовков аутентификации работает корректно и за пределами категории alert; этот конкретный тестовый ключ просто ограничен доступом только на уровне оповещений (обычное ограничение ключа интеграции Opsgenie, а не ошибка).

Справочник API

• Обзор: https://docs.opsgenie.com/docs/api-overview

• Аутентификация: https://docs.opsgenie.com/docs/authentication

• Документация по категориям доступна по ссылкам на боковой панели: https://docs.opsgenie.com/docs/alert-api

Известные пробелы

• Сокращено с 213 до 22 инструментов 2026-08-04. Первоначальная сборка охватывала полный публичный API по 28 категориям согласно более раннему решению о границах. Более позднее решение сократило её до реально используемой категории MSPbots (alert) плюс её базовых CRUD-операций — см. раздел Scope выше, чтобы узнать, что именно было сохранено/удалено в рамках alert, и полный список 27 удалённых категорий (~178 инструментов). Если удалённая категория понадобится позже, те же страницы docs.opsgenie.com/docs/*-api можно повторно распарсить тем же способом, каким были сгенерированы сохранённые инструменты.

• Некоторые сохранённые инструменты по-прежнему изменяют реальное состояние оповещений Opsgenie (opsgenie_alert_delete_alert, opsgenie_alert_close_alert, opsgenie_alert_create_alert и т. д.) — относитесь к ним как к необратимым/изменяющим состояние и подтверждайте с человеком перед вызовом.

• Параметры body не типизированы (dict), а не полностью смоделированы — в docstring каждого инструмента перечислены имена полей, извлечённые из документации Opsgenie, но воспроизведение всех их в виде типизированных параметров Python выходило за рамки механически сгенерированного сервера.

• Исходные данные были извлечены из текстовой документации, а не из машинной спецификации — у Opsgenie нет загружаемой коллекции OpenAPI/Postman, поэтому метод/путь/параметры каждой операции были распарсены из HTML docs.opsgenie.com.

• Только opsgenie_alert_list_alerts (собственный endpoint MSPbots) был проверен вживую с возвратом реальных данных. Остальные 21 инструмент структурно корректны (схема проверена, MCP-протокол tools/list подтверждён, все проходят compile()), но не были индивидуально смоук-тестированы — некоторые из них являются операциями записи/разрушения, которые создали бы, изменили или закрыли реальные оповещения, поэтому они не выполнялись против живого тестового аккаунта.

• Вендор приближается к завершению поддержки (см. предупреждающий баннер в верхней части этого README) — Atlassian рекомендует перейти на Jira Service Management или Compass. Этот MCP нацелен на всё ещё работающий публичный API Opsgenie по состоянию на эту сборку.