Uptimer v2.0.0-preview documentation — it describes the release candidate, and v1.8.0 remains the current release. Commands here pull the preview image :2.0.0-rc15@sha256:945bd3a8fd42800445826df5d0968fd4c86d1d2a2e69f0fb41d897c66b0b0235. The Python SDK for this preview is a local wheel, not a PyPI release. Go to the current release (v1.8.0) →
Reference › MCP (installed binary)

MCP (installed binary)

Let an AI client read your Uptimer, and act on it if you allow it, with one scoped API key.

uptimer mcp lets an AI client (Claude Desktop, Claude Code, Cursor, MCP Inspector, …) read your Resources and Incidents, and act on them if you allow it. The client starts the installed uptimer binary and talks to it over stdin and stdout. Nothing else to install.

The tools call API v3 with one API key. They have no database access and no permissions of their own: the key decides.

1. Make a key

In the UI: API keys → New key.

A full key also works, but it acts as you in every Workspace.

2. Add it to your client

{
  "mcpServers": {
    "uptimer": {
      "command": "/usr/local/bin/uptimer",
      "args": ["--mcp"],
      "env": {
        "UPTIMER_MCP_API_KEY": "<the token>",
        "UPTIMER_MCP_URL": "https://uptimer.example.com"
      }
    }
  }
}

Claude Code:

claude mcp add uptimer \
  -e UPTIMER_MCP_API_KEY=<the token> \
  -e UPTIMER_MCP_URL=https://uptimer.example.com \
  -- /usr/local/bin/uptimer mcp

uptimer --mcp and uptimer mcp are the same. --token and --url exist, but a token on the command line shows in ps, so use the environment. UPTIMER_MCP_URL is where the UI is served (default http://localhost:8080); the API port works too.

With Docker, run the image instead of a local binary:

"command": "docker",
"args": ["run", "-i", "--rm", "-e", "UPTIMER_MCP_API_KEY", "-e", "UPTIMER_MCP_URL",
         "ghcr.io/myuptime-info/uptimer:2.0.0-rc15@sha256:945bd3a8fd42800445826df5d0968fd4c86d1d2a2e69f0fb41d897c66b0b0235", "mcp"]

The key is checked on start. A refused key stops uptimer mcp with a message on stderr; logs never go to stdout.

Tools

ToolNeedsWhat it does
list_workspacesreadWorkspaces the key reaches, with your role
create_workspacefull keycreate a Workspace you own, by name; answers its id. A scoped key does not have it. From the release candidate after 2.0.0-rc2
list_resourcesreada page of Resources with their open Incident; template, state (active, archived, all), meta field values, labels (after 2.0.0-rc7), missing (from 2.0.0-rc9: never_reported, stale or reported_no_data), cursor (1–50)
list_templatesreadthe Templates Resources here can be made from, every revision
get_resourcereadSignals (from 2.0.0-rc9, each with applicability: applicable or not_applicable, missing, and on_demand / not_checked, which from 2.0.0-rc11 also covers an on-demand reading older than its valid_seconds; from 2.0.0-rc11, reset: when a Rule’s recovery reset the Signal’s current reading and which Rule, or null; from 2.0.0-rc9, a Signal with a confirm policy carries its newest reading’s confirmation), Rules with their result and explanation, maintenance
list_observationsreadnewest Observations of a Resource (limit 1–50, default 20; no older pages); from 2.0.0-rc9 a reading of a Signal with a confirm policy carries its confirmation and each confirmer’s reading; its state stays the original
list_incidentsreadIncidents, newest first; filters including rule, lifecycle, acknowledged (true or false; after 2.0.0-rc2), template, resource_state, meta and labels, and a cursor (1–50)
get_incidentreadone Incident and its recorded history, with each transition’s input evidence; from 2.0.0-rc9 an input carries a Signal’s confirmation (status, reason, original) beside the status the Rule read. The Incident’s own confirmation (from confirm_after) is a different thing
list_incident_deliveriesreadwhat was sent about an Incident: delivered, failed or held, with a reason code
acknowledge_incidentacknowledgetake an open Incident on
start_maintenance, end_maintenancemaintenancehold or release a Resource’s notifications
send_test_observationobservesend one Observation, labelled source: mcp-test
send_observationobservepush one Observation: state ok, problem or no_data, a numeric value, optional at, id (at most 64 characters; a longer one is the API’s validation error with details.field id) and reason (a short why, kept with the evidence and alert)
send_observationsobservepush up to 500 Observations for any Resources in one call, each send_observation’s arguments plus resource; one result per item, accepted with its id or rejected with the single send’s error. After 2.0.0-rc7
publish_templatetemplatespublish a pushed-data Template revision (the API v3 manifest); after 2.0.0-rc3 its Rules may use known, all_known and any_known (any number of probes); after 2.0.0-rc4 each Rule may set routes (route by Rule and transition); from 2.0.0-rc9 a Signal may set applies_if, on_demand or a confirm policy, and a comparison if_unknown: false (pushed-data Templates); from 2.0.0-rc11 a Rule may set on_recovery.reset_signals, an on-demand Signal valid_seconds, and a comparison may read a Signal’s confirmation (eq / neq refuted, confirmed, none …). A Rule over the Rule limits (16 comparisons, 4 levels, an action of 1–200 characters) is refused as a validation error and nothing is stored
create_resource, archive_resourceresourcescreate a Resource from a Template by your own key; archive one
label_resourcefull keyset, change or remove a Resource’s own labels ({"env": "prod", "team": null}); after 2.0.0-rc7
rebind_resourcefull keymove a pushed-data Resource to another published revision (template, meta), keeping its id and key; after 2.0.0-rc2. From 2.0.0-rc10 a Signal that keeps its key and kind keeps its history (baselines carry on), and reset_history (a list of Signal keys) starts named ones fresh
list_destinationsfull keythe Workspace’s destinations: id, name, type, channel, enabled, send_on_open, default; never a URL. After 2.0.0-rc5
create_destination, update_destinationfull keyadd a Slack or webhook destination (name, type, url, …), or change one; its URL is never shown back
delete_destinationfull keydelete one; refused with used_by while a live route still uses it
test_destinationfull keysend the test message; delivered, or failed with a reason code
list_destination_deliveriesfull keywhat was sent to one destination, newest first, with a cursor

A write tool is listed only when the key has its action, and API v3 checks it again on every call. With a key for one Workspace, the workspace argument can be left out.

Results carry API v3’s answer as result (and next_cursor for a page). Errors carry API v3’s error as it came: code, error_type, message, details. Ids are the same public ids as the API and the UI. Tokens, destination URLs, delivery payloads and what a destination answered never appear: a failed delivery says only unreachable, http_NNN or not_sent. With a scoped key, a Resource’s secret Template fields read [redacted] and its URL fields carry no user info or credential-named query values; so do Template field defaults. An Observation label whose name marks a credential (api_token, Authorization, …) reads [redacted]; other labels stay. Editing a Resource stays a full key’s, so a redacted value is never written back. A full key reads the real values.

Not everything has a tool. After 2.0.0-rc3, the opened webhook event is switched on per webhook destination in the UI (Settings, the destination’s Also send when an Incident opens; after 2.0.0-rc5 also send_on_open in create_destination and update_destination), and the Resource page’s recorded decision evidence, latest Signals, and the list’s age and open-Incident sorting are in the browser only. A Template’s Rules cannot select Observation labels (REST API); MCP adds none.

A read flow

Ask the client, for example: “Which Incidents are open in Uptimer, and why?” It calls list_incidents with lifecycle: open, then get_incident for the history and list_incident_deliveries for who was told.

A triage flow

With a key scoped to Send Observations, Publish Templates and Create and archive Resources, a client can run the pushed-fleet triage end to end, on the same API v3 behaviour:

  1. publish_template with the guide’s service-triage.json as manifest.
  2. create_resource {template: "service-triage", key: "srv-0042", meta: {provider: "alpha"}}.
  3. send_observation for probe_a, probe_b, origin, service_health (state), and load_ratio (state: ok, value: 0.1), or state: no_data when the ratio is not valid.
  4. list_incidents {template: "service-triage", meta: {provider: "alpha"}}, then get_incident for the transition evidence.
  5. archive_resource for a server that left the inventory.

Audit

Recorded in server_api_audit for every key: each write, refused ones too, and each read of recorded evidence (get_incident, list_incident_deliveries, list_observations). Each row names the key, the person, the Workspace, the path, the status and uptimer-mcp/<version> as the agent. Lists (list_workspaces, list_resources, list_incidents) and get_resource are not recorded.