AlertOps

AlertOps MCP Server

MCP server for AlertOps's incident alerting/on-call API - alerts, message topics, users and their contact methods, groups, configured inbound integrations, and on-call schedules, for AI assistants and the WYRE Conduit gateway.

Authentication

AlertOps' REST API (https://api.alertops.com/api/..., per its published OpenAPI spec at api.alertops.com/swagger/v1/swagger.json) authenticates with a static account-level API key, generated under Account Settings -> Configurations -> Integrations -> API. Unlike most WYRE Conduit sidecars, the key is not sent as a bearer token or custom auth header - AlertOps requires it as an APIKey query-string parameter on every single request, GET and POST alike (live-verified 2026-09-20: an invalid key returns a clean {"reason":"Invalid API Key"} HTTP 401 on every endpoint this connector calls). This connector receives the key per-request via a custom header (never OAuth, same shape as every other static-key WYRE Conduit sidecar) and itself appends ?APIKey=<key> when calling AlertOps' API. In gateway mode the key arrives per-request via the X-AlertOps-Api-Key header; in local/stdio mode it's read once from ALERTOPS_API_KEY. HTTP /mcp also requires an X-Gateway-S2S signature (see HTTP authentication below). The HTTP server refuses to start without a real CONDUIT_S2S_SECRET.

Two separate claims here, at deliberately different confidence levels - don't collapse them into one "read-only" statement:

• Structurally verified (checked directly, stated with full confidence): this connector's own code makes zero calls to a write/mutating AlertOps endpoint. Every function in client.ts calls one of the 11 documented GET operations listed under Tools below; no POST call exists anywhere in src/.
• Vendor-documented, not independently verified (hedged deliberately): AlertOps ships role-based access control with built-in and custom roles built from individually-grantable read-only entitlements (e.g. Messages_View_GlobalAccess, User_View_GlobalAccess, Groups_View_GlobalAccess) - AlertOps' own docs describe a custom role built this way as letting a user "browse incidents, reports, users, and groups but cannot create, modify, or delete anything" (help.alertops.com, Role Based Access Control). A distinct User API Key, shown on a user's own Profile page, is described elsewhere in AlertOps' docs as gated by the UserAPIKey_Add entitlement, implying an API key issued this way inherits the issuing user's role/entitlements. Whether that's actually enforced server-side against this connector's APIKey query parameter and its write endpoints specifically - i.e. whether AlertOps' backend rejects a write call (Create Alert, Close Alert, Assign, etc.) made with a key belonging to a read-only-scoped user, versus that restriction only ever being surfaced in AlertOps' own UI - has not been tested by WYRE. Nobody sent a write call against a live key to check, correctly: that would risk creating a real page/notification against real on-call staff, not something to run without consent. Do not read this connector, or this README, as having established that a read-only-provisioned AlertOps API key technically cannot perform writes - only that this connector's own code never attempts one, and that AlertOps' documented role system supports provisioning a key that way.

Configuration

Copy .env.example. Leave CONDUIT_S2S_SECRET empty in that file.

Env var	Description
ALERTOPS_API_KEY	API key issued under Account Settings -> Configurations -> Integrations -> API. Used by stdio and by HTTP when AUTH_MODE=env.
MCP_TRANSPORT	stdio (default) or http.
AUTH_MODE	env (local default; reads ALERTOPS_API_KEY) or gateway (Docker image and Compose default). Gateway mode requires X-AlertOps-Api-Key on each /mcp request.
CONDUIT_S2S_SECRET	Required to start the HTTP transport. Empty values and known placeholders (changeme, replace-with-a-real-secret, your-s2s-secret, and similar) are rejected: the process logs an error and exits non-zero. The value is never logged. Compose will not start when this is unset.
MCP_ALLOW_INSECURE_DEV	Set to exactly 1 for local development only, to start HTTP when CONDUIT_S2S_SECRET is empty. Logs a warning, skips the X-Gateway-S2S check, and listens on 127.0.0.1 only. A non-loopback MCP_HTTP_HOST is ignored in that mode. A known placeholder secret is still rejected.
MCP_HTTP_HOST	Bind address for HTTP. Defaults to 127.0.0.1 when unset. A configured CONDUIT_S2S_SECRET honors this value (the container image sets 0.0.0.0).
MCP_HTTP_PORT	HTTP port. Defaults to 8080.
LOG_LEVEL	debug | info (default) | warn | error.

/health stays unauthenticated and does not read credentials. The stdio transport does not use CONDUIT_S2S_SECRET.

HTTP authentication

With MCP_TRANSPORT=http and CONDUIT_S2S_SECRET set, every /mcp request must include X-Gateway-S2S. The value is:

t=<unix seconds>,v1=<hex hmac-sha256>

v1 is HMAC-SHA256 over the ASCII message t=<unix seconds> (the same t= prefix that appears in the header), keyed by CONDUIT_S2S_SECRET, encoded as 64 lowercase hex characters. A missing or invalid header returns 401. The secret is never logged.

In AUTH_MODE=gateway, /mcp also requires X-AlertOps-Api-Key. A request missing that header returns 401. Gateway mode uses that header as the only AlertOps credential for the request.

Request limits

• HTTP request bodies are capped at 256 KiB (262144 bytes). After the X-Gateway-S2S check passes, a Content-Length above the cap returns 413 with a JSON-RPC error; bodies without Content-Length are capped by the MCP SDK transport. Unauthenticated requests still get 401 first.
• tools/call arguments are capped at 10,000 elements (every array item and object key at any depth). Larger inputs return an isError tool result and are never dispatched.

These limits address CVE-2026-111768 / GHSA-46jr-4wx8-v453 (memory exhaustion during validation) and GHSA-f897-62hf-6gxq (no request body / batch cap).

Tools

11 read-only tools, one per GET operation in AlertOps' published REST API spec (25 operations total; the other 14 are POST/write and are deliberately excluded - see Scope below).

Alerts

• alertops_list_alerts - list alerts, filterable by status/date range/group/integration/escalation, paginated.
• alertops_get_alert_id_by_inbound_message_id - resolve the AlertID an inbound integration's messageID was mapped to.
• alertops_get_alert_id_by_unique_inbound_id - resolve the AlertID an inbound integration's uniqueInboundID was mapped to.

Users

• alertops_list_users - list users (username, full name, user type).
• alertops_get_user_contact_methods - list a user's configured contact methods (email, phone/SMS). Contact PII.

Groups

• alertops_list_groups - list groups (group ID -> group name).

Topics

• alertops_list_topics - list message topics used for alert routing/escalation.

Integrations

• alertops_list_integrations - list configured inbound integrations (integration rule ID -> integration type).

Schedule

• alertops_get_oncall_now - list who is on-call right now, for every group or one specific group.
• alertops_get_user_schedule - a user's on-call schedule for a date range (max 3 months).
• alertops_get_group_schedule - a group's on-call schedule for a date range (max 3 months).

Scope

This is a deliberately narrow, read-only v1 surface, hard-scoped to exactly 11 of AlertOps' 25 documented operations. AlertOps is a live incident-paging system - every excluded operation either mutates state or can trigger a real page/notification to a human, so none of it is implemented here, by design, not by oversight:

Hard-excluded (creates or mutates a live alert - can page a human) - never implemented:

• POST /api/alert/Create (Alert_Create) - creates a new alert, which pages/notifies its recipients.
• POST /api/alert/Close (Alert_Close) - closes a live alert.
• POST /api/alert/Update (Alert_Update) - updates a field on a live alert.
• POST /api/alert/Assign (Alert_Assign) - assigns a user to an alert.
• POST /api/alert/Note (Alert_Note) - adds a note to an alert.
• POST /api/alert/AddRecipients (Alert_AddRecipients) - adds recipients to an alert, i.e. pages additional people.
• POST /api/alert/Reply (Alert_Reply) - replies to an alert.

Hard-excluded (provisioning/mutation - users, groups, schedules, integrations) - never implemented:

• POST /api/user/CreateUser (User_CreateUser) - creates a new user.
• POST /api/user/CreateOutOfOffice (User_CreateOutOfOffice) - creates an out-of-office record, which changes who gets paged.
• POST /api/group/CreateGroup (Group_CreateGroup) - creates a new group.
• POST /api/group/AddGroupMember (Group_AddGroupMember) - adds a member to a group, which changes who gets paged.
• POST /api/schedule/CreateFixedSchedule (Schedule_CreateFixedSchedule) - creates a fixed on-call schedule.
• POST /api/schedule/CreateRecurringSchedule (Schedule_CreateRecurringSchedule) - creates a recurring on-call schedule.
• POST /api/integration/CreateMaintenanceWindows (Integration_CreateMaintenanceWindows) - creates a maintenance window, which suppresses alerting.

They can be added as a follow-up if there's demand, after a deliberate scope decision - not by default.

Development

npm install
npm run build
npm test
npm run lint   # tsc --noEmit

Docker

The image listens on 0.0.0.0 inside the container (MCP_HTTP_HOST) and defaults to AUTH_MODE=gateway. Publish the port on loopback and pass a generated S2S secret. Startup rejects an empty CONDUIT_S2S_SECRET and known placeholders (your-s2s-secret, changeme, and similar), so each command below creates a value with openssl rand -hex 32 instead of embedding one. In gateway mode the AlertOps API key arrives on each request as X-AlertOps-Api-Key.

docker build -t alertops-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$(openssl rand -hex 32)" \
  -p 127.0.0.1:8080:8080 \
  alertops-mcp

Compose refuses to start when CONDUIT_S2S_SECRET is unset. The Compose service is gateway mode, sets no ALERTOPS_API_KEY, and publishes 127.0.0.1:8080:8080. Export one secret when a gateway must sign requests with the same value the container receives:

export CONDUIT_S2S_SECRET="$(openssl rand -hex 32)"
docker compose up

Single-tenant HTTP (AUTH_MODE=env) still requires the S2S secret, then uses ALERTOPS_API_KEY from the environment. Export that key before running the command.

docker run \
  -e CONDUIT_S2S_SECRET="$(openssl rand -hex 32)" \
  -e AUTH_MODE=env \
  -e ALERTOPS_API_KEY \
  -p 127.0.0.1:8080:8080 \
  alertops-mcp

Local HTTP without a secret is development-only. It binds 127.0.0.1 even if MCP_HTTP_HOST is 0.0.0.0, and logs a warning:

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm run start:http

License

Apache-2.0