SaaS Alerts API Patterns

SaaS Alerts MCP Tools & API Patterns

Overview

SaaS Alerts is a SaaS security monitoring platform for MSPs. It monitors M365, Google Workspace, and other SaaS applications for security events, anomalies, and policy violations across all managed customer tenants. The MSP (partner) sees all customers under their account; each customer has one or more accounts (e.g., an M365 tenant, a Google Workspace domain).

Anti-triggers

• Working the alert queue. This skill covers filters, cursors, and the customer hierarchy; sweeping, ranking, and dispositioning events is saas-alerts-triage.
• A SaaS Alerts customer treated as an M365 tenant. They describe the same organisation but are separate records with separate IDs, and this API cannot read or change tenant configuration — use cipp-tenants.

Connection & Authentication

SaaS Alerts uses an API key passed as a request header. The key is issued in the SaaS Alerts partner portal.

The gateway maps the environment variable SAAS_ALERTS_API_KEY onto the X-SaaS-Alerts-API-Key header automatically. Internally the MCP server forwards this to the SaaS Alerts API as the api_key header — you do not need to construct that header yourself.

export SAAS_ALERTS_API_KEY="your-partner-api-key"

Hierarchy

MSP Partner
  └── Customer (managed organization)
        └── Account (M365 tenant / Google Workspace domain / other SaaS)
              └── User
                    └── Events / Alerts

Always navigate top-down: identify the customer first, then scope to an account or user. saas_alerts_customers_list is the standard entry point.

Navigation Tools

Call saas_alerts_status at the start of any session to confirm the gateway and upstream API are reachable before running queries.

Functional Tool Surface

Tools follow saas_alerts_<domain>_<action>. Key domains:

• events — saas_alerts_events_query, saas_alerts_events_count, saas_alerts_events_query_advanced, saas_alerts_events_count_advanced, saas_alerts_events_scroll, saas_alerts_recommended_actions
• customers — saas_alerts_customers_list, saas_alerts_customers_get
• users — saas_alerts_users_list_partner, saas_alerts_users_list_by_customer, saas_alerts_users_get_msp
• devices — saas_alerts_devices_list_orgs, saas_alerts_devices_list_mapped, saas_alerts_devices_list_unmapped, saas_alerts_devices_list_ignored
• billing — saas_alerts_billing_list_dates, saas_alerts_billing_get_details
• reports — saas_alerts_reports_list_scheduled, saas_alerts_reports_get_scheduled
• partner — saas_alerts_partner_get_profile

The naming convention does not imply a get-by-id for every domain. Users and devices are list-only. There is no per-user get and no per-device get (saas-alerts-mcp/src/domains/users.ts, saas-alerts-mcp/src/domains/devices.ts); an earlier revision of this list named four tools — a bare users-list, a per-user get, a bare devices-list and a per-device get — and none of them exist. Resolving a user or device ID to a record means listing the relevant scope and matching client-side. Note that saas_alerts_users_get_msp is not the missing per-user get: it takes no arguments and always returns the API key's own MSP profile.

Write/admin tools (customers_create/update/delete, set_whitelists, reports_create/delete_scheduled, partner_update_branding) mutate state and require explicit user confirmation before calling.

Event Filters

saas_alerts_events_query accepts:

For cross-tenant pattern detection use saas_alerts_events_query_advanced which accepts richer filter expressions across all customers simultaneously.

Pagination

Two mechanisms, and they are not interchangeable:

• saas_alerts_events_query pages with size and from. Walk from forward until a page comes back short.
• saas_alerts_events_query_advanced returns a scroll ID; feed it to saas_alerts_events_scroll and keep calling until the result set is exhausted.

Large tenants can return thousands of events in a 24-hour window, so a first page is never evidence of a complete answer. When you only need a total, saas_alerts_events_count and saas_alerts_events_count_advanced avoid paging entirely.

Error Handling

Best Practices

• Scope queries to a customer or time window before listing events — an unscoped query against all customers in a large MSP account can be slow.
• Pair events with saas_alerts_recommended_actions for the same alert to give the analyst actionable next steps immediately.
• For write operations (set_whitelists, customers_update) always show the operator the current state before making changes.

Related Skills

• triage — Sweep and prioritize the SaaS Alerts queue