<!-- Generated by jmi-server from crates/server/src/api/mcp/tools.rs; do not edit. -->

# 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`](#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`](#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`](#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`](#list_monitors) | viewer | read | The organisation's monitors with their current status per location and 24 h uptime, filtered and paged. |
| [`get_monitor`](#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`](#create_monitor) | member | write | Create a monitor. |
| [`update_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`](#pause_monitor) | member | write | Stop checking a monitor (and alerting for it) until it is resumed. |
| [`resume_monitor`](#resume_monitor) | member | write | Start checking a paused monitor again (subject to the plan's limits). |
| [`delete_monitor`](#delete_monitor) | member | write, destructive | Delete a monitor with its history, incidents and pending notifications. |
| [`preview_check`](#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`](#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`](#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`](#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`](#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`](#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`](#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`](#acknowledge_incident) | member | write | Acknowledge an open incident: reminders stop and the team sees someone is on it. |
| [`add_incident_note`](#add_incident_note) | member | write | Add a note (1-2000 characters) to an incident's timeline. |
| [`list_contacts`](#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`](#list_notifications) | viewer | read | Alerts sent or attempted, newest first, with each delivery attempt and the provider's status. |
| [`list_members`](#list_members) | admin | read | The organisation's members with their roles (owner, admin, member, viewer) and when they were last active. |
| [`get_audit_log`](#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. |