SaaS Alerts

saas-alerts-mcp

Model Context Protocol server for Kaseya SaaS Alerts — a SaaS security monitoring platform for M365 and Google Workspace events.

Part of the WYRE Technology MCP fleet.

Features

Exposes the full SaaS Alerts External Partner API (v0.20.0) through 30 MCP tools organized by domain:

Domain	Tools
events	Query/count security events by severity, customer, user, event type; advanced Elasticsearch queries; scroll pagination; recommended actions
customers	List, get, create, update, delete customers; set IP/country and account whitelists
users	MSP user info, partner users, customer users
devices	Unify mapped/unmapped/ignored devices, device organizations
billing	Billing details by date, billing date history
reports	List/get/create/delete scheduled reports
partner	Partner profile, branding settings

Write/destructive tools require user confirmation via MCP elicitation (fail-open: proceeds if client doesn't support elicitation).

Authentication

SaaS Alerts uses an API key sent as the api_key HTTP header.

Generate your API key in the SaaS Alerts UI under Settings → API Keys.

Copy .env.example. Leave CONDUIT_S2S_SECRET empty in that file and never commit a real value.

Variable	Required	Description
SAAS_ALERTS_API_KEY	For stdio and AUTH_MODE=env	SaaS Alerts API key. Gateway mode does not read it.
MCP_TRANSPORT	No	stdio (default) or http
AUTH_MODE	No	gateway (Docker image and Compose default) or env. Gateway mode requires X-SaaS-Alerts-API-Key on each /mcp request and never falls back to SAAS_ALERTS_API_KEY.
CONDUIT_S2S_SECRET	Yes for HTTP	Service-to-service secret. The HTTP server logs an error and exits non-zero when this is empty or a known placeholder (changeme, secret, your-s2s-secret, and the other example values). Compose will not start when it is unset. The value is never logged.
MCP_ALLOW_INSECURE_DEV	No	Set to 1 only for local development to start HTTP without CONDUIT_S2S_SECRET. The process logs a warning, does not enforce X-Gateway-S2S, and listens on 127.0.0.1 only. A wider MCP_HTTP_HOST (including 0.0.0.0) is overridden. A placeholder secret is still rejected.
MCP_HTTP_HOST	No	Bind address when a real CONDUIT_S2S_SECRET is set. Defaults to 127.0.0.1. The container image sets 0.0.0.0. Without a real secret the listener is forced to 127.0.0.1.
MCP_HTTP_PORT	No	HTTP port. Defaults to 8080.

/health and /healthz stay unauthenticated and do not read credentials. The stdio transport does not use CONDUIT_S2S_SECRET.

X-Gateway-S2S signing

With MCP_TRANSPORT=http and a real CONDUIT_S2S_SECRET, every /mcp request must include X-Gateway-S2S. A missing or invalid header returns 401 before any vendor credential is read.

The header value is t=<unix seconds>,v1=<hex hmac-sha256>:

1. Set t to the current unix time in seconds.
2. Sign the ASCII message t=<unix seconds> with HMAC-SHA256, using CONDUIT_S2S_SECRET as the key.
3. Hex-encode the digest (64 lowercase hex characters) and send t=<unix seconds>,v1=<hex>.

The timestamp must be within 300 seconds of the server clock. Example:

import { createHmac } from 'node:crypto';

const t = Math.floor(Date.now() / 1000);
const v1 = createHmac('sha256', process.env.CONDUIT_S2S_SECRET).update(`t=${t}`).digest('hex');
const xGatewayS2s = `t=${t},v1=${v1}`;

Local / stdio mode

export SAAS_ALERTS_API_KEY=your-api-key
node dist/index.js

HTTP mode

CONDUIT_S2S_SECRET is required. If it is empty, the process logs an error and exits non-zero.

export CONDUIT_S2S_SECRET="$(openssl rand -hex 32)"
export SAAS_ALERTS_API_KEY=your-api-key
export MCP_TRANSPORT=http
export AUTH_MODE=env
export MCP_HTTP_PORT=8080
node dist/http.js

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

WYRE Gateway mode

When running behind the WYRE MCP Gateway, set AUTH_MODE=gateway (the image and Compose default). The gateway signs each request with X-Gateway-S2S and injects the API key via X-SaaS-Alerts-API-Key. A request missing that credential header returns 401 and does not use SAAS_ALERTS_API_KEY from the environment.

await fetch('http://127.0.0.1:8080/mcp', {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    accept: 'application/json, text/event-stream',
    'x-gateway-s2s': xGatewayS2s,
    'x-saas-alerts-api-key': apiKey,
  },
  body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list' }),
});

Running with Docker

The image listens on 0.0.0.0 inside the container and defaults to AUTH_MODE=gateway. Publish the port on loopback and pass the S2S secret. In gateway mode the SaaS Alerts API key arrives on each request; it is not read from the environment.

docker build -t saas-alerts-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  saas-alerts-mcp

Compose refuses to start when CONDUIT_S2S_SECRET is unset, sets AUTH_MODE=gateway, publishes 127.0.0.1:8080:8080, and does not pass SAAS_ALERTS_API_KEY into the gateway service:

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

Single-tenant HTTP (AUTH_MODE=env) still requires the S2S secret, then uses SAAS_ALERTS_API_KEY:

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e SAAS_ALERTS_API_KEY=your-key \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/wyre-ai/saas-alerts-mcp:latest

Development

npm install
npm run build
npm test
npm run lint
node scripts/lint-destructive-warnings.mjs src

Destructive tool confirmation

Tools that permanently delete data (customer delete, scheduled report delete) carry:

• ⚠ DESTRUCTIVE — IRREVERSIBLE description prefix
• annotations.destructiveHint: true
• Elicitation confirmation guard (additive — proceeds if client doesn't support elicitation)

Always confirm with the user before invoking these tools.

License

Apache-2.0 — see LICENSE.