saas-alerts-mcp

A fully self-contained Model Context Protocol server for Kaseya SaaS Alerts — the SaaS security monitoring platform for Microsoft 365 and Google Workspace events.

It wraps the SaaS Alerts External Partner API (Reports) v0.20.0 and exposes it as 30 MCP tools plus 3 workflow prompts. The API client is vendored in-tree (src/sdk), so the server builds and runs with a single public dependency (@modelcontextprotocol/sdk) — no private packages, no external SDK to install.

Features

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

• Two navigation helpers — saas_alerts_navigate (browse a domain's tools) and saas_alerts_status (connectivity check against the authenticated MSP user).
• Three prompts — alert-triage, customer-alert-summary, cross-tenant-anomaly.
• Write/destructive guards — mutating tools carry annotations.destructiveHint and, where irreversible, a ⚠ DESTRUCTIVE description prefix. They request confirmation via MCP elicitation and fail open (proceed) if the client doesn't support it.
• Empty-result guard — list tools return isError with a clear "No … found" message instead of an empty payload, to stop the model hallucinating results.

Authentication

SaaS Alerts authenticates with an API key sent as the api_key HTTP header (not Authorization: Bearer). Generate one in the SaaS Alerts UI under Settings → API Keys.

Set it via the SAAS_ALERTS_API_KEY environment variable.

Quick start

npm install      # also builds via the `prepare` script
npm run build    # or build explicitly
export SAAS_ALERTS_API_KEY=your-api-key
node dist/index.js          # stdio transport

Importing into Hermes (or any MCP host)

The server speaks standard MCP over stdio, so it drops into any MCP host that uses the common mcpServers config block. Build it once (npm run build), then point your host at dist/index.js.

Copy .mcp.json.example into your host's MCP config and edit the path + key:

{
  "mcpServers": {
    "saas-alerts": {
      "command": "node",
      "args": ["/absolute/path/to/saas-alerts-mcp/dist/index.js"],
      "env": {
        "SAAS_ALERTS_API_KEY": "your-saas-alerts-api-key",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

After import, the host will discover all 30 saas_alerts_* tools. Call saas_alerts_status first to confirm the key is valid and connectivity is up.

Tip: if your Hermes deployment prefers a network endpoint over a spawned process, run the server in HTTP mode (below) and register the http://host:8080/mcp URL instead.

HTTP mode

export SAAS_ALERTS_API_KEY=your-api-key
export MCP_TRANSPORT=http
export MCP_HTTP_PORT=8080
node dist/http.js

• POST /mcp — MCP endpoint (stateless streamable-HTTP, JSON responses).
• GET /health — liveness probe (does not require credentials).

Gateway mode (multi-tenant)

Set AUTH_MODE=gateway. The server then reads the per-request API key from the X-SaaS-Alerts-API-Key header instead of the environment, and isolates each request's credentials in an AsyncLocalStorage context. The HTTP transport is intentionally kept stateless to preserve that per-request tenant isolation.

Running with Docker

export SAAS_ALERTS_API_KEY=your-api-key
docker compose up --build

The container runs HTTP mode on port 8080 with a /health healthcheck, as a non-root user.

Configuration

Variable	Default	Description
SAAS_ALERTS_API_KEY	—	Required (env/stdio mode). Sent as the api_key header.
MCP_TRANSPORT	stdio	stdio or http.
MCP_HTTP_PORT	8080	HTTP mode listen port.
MCP_HTTP_HOST	0.0.0.0	HTTP mode bind host.
AUTH_MODE	env	env reads the key locally; gateway reads X-SaaS-Alerts-API-Key per request.
LOG_LEVEL	info	debug | info | warn | error (logs go to stderr).

Development

npm install
npm run build              # bundle to dist/ (ESM, with .d.ts)
npm test                   # vitest — SDK transport/resources + MCP domain handlers
npm run lint               # tsc --noEmit
npm run lint:destructive   # assert destructive tools carry warnings

Architecture

src/
  index.ts        stdio entrypoint
  http.ts         streamable-HTTP entrypoint (+ gateway mode)
  server.ts       MCP Server wiring: tools/list, tools/call, prompts
  prompts.ts      3 workflow prompts
  domains/        one handler per API domain (events, customers, …)
  elicitation/    destructive-action confirmation guard (fail-open)
  utils/          request-scoped credentials, result helpers, logger
  sdk/            vendored typed client for the SaaS Alerts Partner API
    http.ts       fetch transport: retries, timeouts, key redaction, typed errors
    resources/    one class per domain, mapping methods → REST endpoints
    client.ts     SaasAlertsClient façade

The API base URL defaults to the production host (https://us-central1-the-byway-248217.cloudfunctions.net/reportApi/api/v1) and can be overridden by constructing SaasAlertsClient with a baseUrl (dev/QA hosts are documented in the OpenAPI spec).

Attribution

The MCP surface design (domain layout, tool naming, destructive-action conventions) follows the open-source wyre-technology/saas-alerts-mcp project. This build vendors the API client in-tree so it is fully buildable and importable standalone.

License

Apache-2.0 — see LICENSE.