MCP tools

Every tool works on the organisation of the API token in use. tools/list returns only the tools the token's effective role can use.

Tool	Least role	Kind	What it does
`whoami`	viewer	read	The API token in use: its name, role, effective role (what it may do: viewer reads; member also changes monitors, incidents and contacts; admin also reads members and the audit log) and the organisation it works on.
`get_overview`	viewer	read	Counts of monitors by status (up, down, degraded, no_data, unknown, paused), the open incidents (newest first, up to 20), the latest status changes and plan usage.
`list_locations`	viewer	read	The locations monitors are checked from: `code` (e.g. `lon1`), name, region (`eu`, `na`, ...) and whether it is available.
`list_monitors`	viewer	read	The organisation's monitors with their current status per location and 24 h uptime, filtered and paged.
`get_monitor`	viewer	read	One monitor: its spec, interval, locations, thresholds, contacts, current status per location, open incident and `version` (pass it as `if_match` when updating).
`create_monitor`	member	write	Create a monitor.
`update_monitor`	member	write	Change a monitor: give `monitor_id` and only the fields to change (JSON merge patch: `spec` is merged field by field, arrays are replaced whole, `null` clears a nullable field).
`pause_monitor`	member	write	Stop checking a monitor (and alerting for it) until it is resumed.
`resume_monitor`	member	write	Start checking a paused monitor again (subject to the plan's limits).
`delete_monitor`	member	write, destructive	Delete a monitor with its history, incidents and pending notifications.
`preview_check`	member	read	Run a check once, now, from one location, and return its result (outcome, error kind, timings) without saving anything or alerting.
`get_monitor_results`	viewer	read	A monitor's individual check results, newest first: per location, outcome (up, degraded, down, error = the probe's own problem), error kind and detail, HTTP status, latency and timings.
`get_monitor_pings`	viewer	read	A heartbeat monitor's ping history, newest first (the newest 100 are kept): when each ping arrived, success or fail (the job reported a failure), the HTTP method, the client's address and user agent.
`get_monitor_uptime`	viewer	read	A monitor's uptime ratio and seconds down, degraded, without data and paused, for the windows 24h, 7d, 30d and 90d, or for one `from`-`to` range.
`set_monitor_contacts`	member	write	Replace the set of contacts a monitor alerts (contact ids `con_…` from list_contacts; an empty list alerts nobody).
`list_incidents`	viewer	read	Incidents (a monitor down or degraded, confirmed from several locations), newest first: status open or resolved, severity, cause, duration, acknowledgement.
`get_incident`	viewer	read	One incident with its timeline (opened, status changes, acknowledgement, notes, resolution), the root cause per location and the notifications sent.
`acknowledge_incident`	member	write	Acknowledge an open incident: reminders stop and the team sees someone is on it.
`add_incident_note`	member	write	Add a note (1-2000 characters) to an incident's timeline.
`list_contacts`	viewer	read	Where alerts go: email addresses, SMS and phone call numbers, Pushover, Discord, PagerDuty, Slack and Microsoft Teams destinations and webhooks, with their status (unverified, active, disabled) and the alerts they get (down, recovered, degraded).
`list_notifications`	viewer	read	Alerts sent or attempted, newest first, with each delivery attempt and the provider's status.
`list_members`	admin	read	The organisation's members with their roles (owner, admin, member, viewer) and when they were last active.
`get_audit_log`	admin	read	Who changed what in the organisation, newest first: actor, action (e.g. `monitor.updated`), target and changed fields.

`whoami`

The API token in use: its name, role, effective role (what it may do: viewer reads; member also changes monitors, incidents and contacts; admin also reads members and the audit log) and the organisation it works on. Every other tool acts on that organisation.

Least role: viewer. Annotations: readOnly true, destructive false, idempotent true.

Arguments: none.

`get_overview`

Counts of monitors by status (up, down, degraded, no_data, unknown, paused), the open incidents (newest first, up to 20), the latest status changes and plan usage. Start here to answer "is anything down?".

Least role: viewer. Annotations: readOnly true, destructive false, idempotent true.

Arguments: none.

`list_locations`

The locations monitors are checked from: code (e.g. lon1), name, region (eu, na, ...) and whether it is available. Use the codes and regions in a monitor's locations and in preview_check.

Least role: viewer. Annotations: readOnly true, destructive false, idempotent true.

Arguments: none.

`list_monitors`

The organisation's monitors with their current status per location and 24 h uptime, filtered and paged. Pass next_cursor back as cursor for the next page.

Least role: viewer. Annotations: readOnly true, destructive false, idempotent true.

Argument	Type	Required	Notes
`cursor`	string	no	Opaque `next_cursor` of the previous page.
`dir`	string	no	One of: asc, desc.
`kind`	string	no	Comma-separated monitor kinds: icmp, http, http_adv, tcp, ssl_expiry, domain_expiry, imap, smtp, heartbeat.
`label`	string	no	One label.
`limit`	integer	no	Page size, default 50.
`q`	string	no	Substring of the name or target.
`run_state`	string	no	Comma-separated: active, paused, system_paused.
`sort`	string	no	One of: created_at, name, status, status_since.
`status`	string	no	Comma-separated: unknown, up, down, degraded, no_data, paused.

`get_monitor`

One monitor: its spec, interval, locations, thresholds, contacts, current status per location, open incident and version (pass it as if_match when updating).

Least role: viewer. Annotations: readOnly true, destructive false, idempotent true.

Argument	Type	Required	Notes
`monitor_id`	string	yes	Monitor id (`mon_…`).

`create_monitor`

Create a monitor. kind is one of icmp, http, http_adv, tcp, ssl_expiry, domain_expiry, imap, smtp, heartbeat, and spec holds that kind's fields: icmp {host}; tcp {host, port}; http {url, keyword?}; http_adv {url, method?, headers?, body?, expected_status? e.g. ["200-299"], assertions? e.g. [{"type": "body_contains", "value": "ok"}]}; ssl_expiry {host, port?, cert_expiry_warn_days?}; domain_expiry {domain, expiry_warn_days?} (interval_s must be 86400; omit locations and the thresholds); imap/smtp {host, port, tls: implicit|starttls|none}; heartbeat {grace_s?} (interval_s is the period between pings, 60-604800; omit locations and the thresholds; the response's ping_url is what the job requests). interval_s is 30, 60, 120, 300, 600, 900, 1800 or 3600 (at least the plan minimum). locations is {"mode": "regions", "regions": ["eu", "na"]} or {"mode": "locations", "codes": ["lon1", "fra1"]} (at least 2 locations; codes from list_locations). Omitting contact_ids attaches the organisation's auto-attach contacts. Test a target first with preview_check. Validation problems come back as an error naming each field.

Least role: member. Annotations: readOnly false, destructive false, idempotent false.

Argument	Type	Required	Notes
`contact_ids`	array \| null	no	At most 100; omitted = every `auto_attach` contact.
`degraded_after_ms`	integer \| null	no	`http_adv` only; 100-30000 and below the time budget; `null` = off.
`failure_threshold`	integer \| null	no	1-10, default 2; for `domain_expiry` 1, the default (a second probe confirms each change instead); for `heartbeat` 1.
`idempotency_key`	string	no	Optional: repeat a call with the same key to get the first result instead of creating twice.
`interval_s`	integer	yes	30, 60, 120, 300, 600, 900, 1800 or 3600, at least the plan minimum. `domain_expiry`: 86400 only. `heartbeat`: the period between pings, 60-604800 (no plan minimum).
`kind`	MonitorKind	yes	Immutable after create.
`labels`	array	no	At most 10, each 1-32 characters of `[a-z0-9-_.]`.
`locations`	see schema	no
`name`	string	yes	1-100 characters.
`paused`	boolean	no
`recovery_threshold`	integer \| null	no	1-10, default 2; for `domain_expiry` and `heartbeat` 1, the default.
`reminder_interval_s`	integer \| null	no	`null` = no reminders; 900-86400.
`spec`	MonitorSpecInput	yes	The per-kind spec without the type tag (probes-and-checks.md §5): the `MonitorSpecInput` schema of `kind`; secret fields are write-only.

`update_monitor`

Change a monitor: give monitor_id and only the fields to change (JSON merge patch: spec is merged field by field, arrays are replaced whole, null clears a nullable field). kind cannot change. paused: true|false pauses or resumes. Pass the version you read as if_match to avoid overwriting someone else's change.

Least role: member. Annotations: readOnly false, destructive false, idempotent true.

Argument	Type	Required	Notes
`contact_ids`	array \| null	no
`degraded_after_ms`	integer \| null	no
`failure_threshold`	integer \| null	no
`if_match`	integer	no	The monitor's `version` you last read; the call fails with `precondition_failed` if it changed since.
`interval_s`	integer \| null	no
`kind`	see schema	no
`labels`	array \| null	no
`locations`	see schema	no
`monitor_id`	string	yes	Monitor id (`mon_…`).
`name`	string \| null	no
`paused`	boolean \| null	no	`false` runs the same checks as `POST .../resume`.
`recovery_threshold`	integer \| null	no
`reminder_interval_s`	integer \| null	no
`spec`	object \| null	no	Merged into the stored spec (RFC 7396): any subset of the `MonitorSpecInput` schema of the monitor's kind.

`pause_monitor`

Stop checking a monitor (and alerting for it) until it is resumed. An open incident is resolved as paused.

Least role: member. Annotations: readOnly false, destructive false, idempotent true.

Argument	Type	Required	Notes
`monitor_id`	string	yes	Monitor id (`mon_…`).

`resume_monitor`

Start checking a paused monitor again (subject to the plan's limits).

Least role: member. Annotations: readOnly false, destructive false, idempotent true.

Argument	Type	Required	Notes
`monitor_id`	string	yes	Monitor id (`mon_…`).

`delete_monitor`

Delete a monitor with its history, incidents and pending notifications. This cannot be undone; confirm with the user first.

Least role: member. Annotations: readOnly false, destructive true, idempotent true.

Argument	Type	Required	Notes
`if_match`	integer	no	The monitor's `version` you last read; the call fails with `precondition_failed` if it changed since.
`monitor_id`	string	yes	Monitor id (`mon_…`).

`preview_check`

Run a check once, now, from one location, and return its result (outcome, error kind, timings) without saving anything or alerting. Takes kind and spec as for create_monitor and a location code. Use it to test a target before creating a monitor. Can take up to about 45 seconds.

Least role: member. Annotations: readOnly true, destructive false, idempotent false.

Argument	Type	Required	Notes
`kind`	MonitorKind	yes
`location`	string	yes	Location code.
`spec`	MonitorSpecInput	yes	The spec as in `MonitorInput` (secrets inline).

`get_monitor_results`

A monitor's individual check results, newest first: per location, outcome (up, degraded, down, error = the probe's own problem), error kind and detail, HTTP status, latency and timings. Default window: the last 24 hours; at most 7 days per call.

Least role: viewer. Annotations: readOnly true, destructive false, idempotent true.

Argument	Type	Required	Notes
`cursor`	string	no	Opaque `next_cursor` of the previous page.
`from`	string	no	RFC 3339 timestamp.
`limit`	integer	no	Page size, default 50.
`location`	string	no	A location code.
`monitor_id`	string	yes	Monitor id (`mon_…`).
`outcome`	string	no	Comma-separated: up, degraded, down, error.
`to`	string	no	RFC 3339 timestamp.

`get_monitor_pings`

A heartbeat monitor's ping history, newest first (the newest 100 are kept): when each ping arrived, success or fail (the job reported a failure), the HTTP method, the client's address and user agent.

Least role: viewer. Annotations: readOnly true, destructive false, idempotent true.

Argument	Type	Required	Notes
`limit`	integer	no	How many, default 50.
`monitor_id`	string	yes	Monitor id (`mon_…`).

`get_monitor_uptime`

A monitor's uptime ratio and seconds down, degraded, without data and paused, for the windows 24h, 7d, 30d and 90d, or for one from-to range.

Least role: viewer. Annotations: readOnly true, destructive false, idempotent true.

Argument	Type	Required	Notes
`from`	string	no	RFC 3339 timestamp.
`monitor_id`	string	yes	Monitor id (`mon_…`).
`to`	string	no	RFC 3339 timestamp.
`windows`	string	no	Comma-separated of 24h, 7d, 30d, 90d (default all).

`set_monitor_contacts`

Replace the set of contacts a monitor alerts (contact ids con_… from list_contacts; an empty list alerts nobody).

Least role: member. Annotations: readOnly false, destructive false, idempotent true.

Argument	Type	Required	Notes
`contact_ids`	array	yes
`monitor_id`	string	yes	Monitor id (`mon_…`).

`list_incidents`

Incidents (a monitor down or degraded, confirmed from several locations), newest first: status open or resolved, severity, cause, duration, acknowledgement.

Least role: viewer. Annotations: readOnly true, destructive false, idempotent true.

Argument	Type	Required	Notes
`cursor`	string	no	Opaque `next_cursor` of the previous page.
`from`	string	no	RFC 3339 timestamp.
`limit`	integer	no	Page size, default 50.
`monitor_id`	string	no	Monitor id (`mon_…`).
`severity`	string	no	One of: down, degraded.
`status`	string	no	One of: open, resolved.
`to`	string	no	RFC 3339 timestamp.

`get_incident`

One incident with its timeline (opened, status changes, acknowledgement, notes, resolution), the root cause per location and the notifications sent.

Least role: viewer. Annotations: readOnly true, destructive false, idempotent true.

Argument	Type	Required	Notes
`incident_id`	string	yes	Incident id (`inc_…`).

`acknowledge_incident`

Acknowledge an open incident: reminders stop and the team sees someone is on it.

Least role: member. Annotations: readOnly false, destructive false, idempotent true.

Argument	Type	Required	Notes
`incident_id`	string	yes	Incident id (`inc_…`).

`add_incident_note`

Add a note (1-2000 characters) to an incident's timeline.

Least role: member. Annotations: readOnly false, destructive false, idempotent false.

Argument	Type	Required	Notes
`body`	string	yes
`incident_id`	string	yes	Incident id (`inc_…`).

`list_contacts`

Where alerts go: email addresses, SMS and phone call numbers, Pushover, Discord, PagerDuty, Slack and Microsoft Teams destinations and webhooks, with their status (unverified, active, disabled) and the alerts they get (down, recovered, degraded). Secrets are never shown.

Least role: viewer. Annotations: readOnly true, destructive false, idempotent true.

Argument	Type	Required	Notes
`cursor`	string	no	Opaque `next_cursor` of the previous page.
`kind`	string	no	One of: email, sms, voice, pushover, discord, pagerduty, slack, webhook, teams.
`limit`	integer	no	Page size, default 50.
`status`	string	no	One of: unverified, active, disabled.

`list_notifications`

Alerts sent or attempted, newest first, with each delivery attempt and the provider's status. Filter by contact, incident or monitor to answer "was anyone told?".

Least role: viewer. Annotations: readOnly true, destructive false, idempotent true.

Argument	Type	Required	Notes
`contact_id`	string	no
`cursor`	string	no	Opaque `next_cursor` of the previous page.
`incident_id`	string	no	Incident id (`inc_…`).
`kind`	string	no	down, recovered, degraded, flapping, reminder, test, ...
`limit`	integer	no	Page size, default 50.
`monitor_id`	string	no	Monitor id (`mon_…`).
`status`	string	no	One of: pending, sending, sent, failed, cancelled, suppressed.

`list_members`

The organisation's members with their roles (owner, admin, member, viewer) and when they were last active.

Least role: admin. Annotations: readOnly true, destructive false, idempotent true.

Arguments: none.

`get_audit_log`

Who changed what in the organisation, newest first: actor, action (e.g. monitor.updated), target and changed fields. Entries made with an API token name it in data.api_token.

Least role: admin. Annotations: readOnly true, destructive false, idempotent true.

Argument	Type	Required	Notes
`action`	string	no	Exact action, e.g. monitor.updated.
`actor`	string	no
`cursor`	string	no	Opaque `next_cursor` of the previous page.
`limit`	integer	no	Page size, default 50.