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

• 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

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.