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>:
- Set
tto the current unix time in seconds. - Sign the ASCII message
t=<unix seconds>with HMAC-SHA256, usingCONDUIT_S2S_SECRETas the key. - 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 — IRREVERSIBLEdescription prefixannotations.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.