Healthchecks

healthchecks-mcp

A Model Context Protocol (MCP) server for Healthchecks, the dead man's switch for cron jobs and scheduled tasks — it alerts you when a job stops checking in. Works against the hosted service and against a self-hosted instance alike.

Lets MCP clients like Claude Code, Claude Desktop or Codex see which scheduled jobs are healthy, read the output the failing one reported, and create or adjust checks — with the irreversible operations behind a confirmation token and the write tools switchable off entirely.

Fourteen tools is the ceiling, not the floor: HEALTHCHECKS_ALLOW_TOOLS=essential registers a curated seven instead, and a model picks the right tool far more reliably from seven than from fourteen — see choosing which tools load.

What makes it different

It reads the ping bodies. get_ping_body returns what a job actually printed when it reported failure. Every other question — which check is down, since when, how often — is one step away from that one, and it is the endpoint the other Healthchecks MCP servers leave out.

Read-only API keys work properly. Healthchecks hands a read-only key a different object: no uuid, no ping_url, no channels — a 40-character unique_key instead. This server addresses checks by either, and get_api_key_info tells you up front which kind of key you configured and which tools it cannot reach, rather than leaving you with a 401 missing api key for a key that was sent.

It never pings a check. Pinging is how a job reports that it ran. A tool that could ping would let a model make a dead job look alive, which is the one thing monitoring must not allow — see Not exposed, on purpose.

It knows where this API is sharp. timeout and schedule cannot be combined because the upstream silently discards one of them; tags are validated against their space separator and keywords against their comma; a new check is given every integration unless you say otherwise, because the API's own default is a check that alerts nobody.

Requirements

• Node.js ≥ 22
• A Healthchecks project API key — Project Settings → API Access. Keys are per project, not per account, and are exactly 32 characters long.

Configuration

HEALTHCHECKS_URL is the site root, not the API root: https://hc.example.net, not https://hc.example.net/api/v3. Both are accepted — the suffix is trimmed — because the API documentation spells every example the long way.

Use https://. Over plain http the API key travels unencrypted; the server prints a warning unless the host is local. For self-signed certificates prefer a proper internal CA over HEALTHCHECKS_INSECURE_TLS.

Without an API key the server still starts and lists its tools (so registries and inspectors can introspect it), but every call except get_status fails with setup instructions instead of reaching the API.

Read-only keys. Healthchecks gates three tools that only read — list_pings, get_ping_body and list_integrations — behind a read-write key anyway. With a read-only key those fail, along with all five write tools.

The failure does not look like a permission problem: the API answers 401 {"error": "wrong api key"}, which reads as if the key were wrong or missing. It is not — those three tools translate it into what actually happened. get_api_key_info reports which kind of key is configured, and HEALTHCHECKS_DENY_TOOLS is the tidy way to stop offering them at all.

Choosing which tools load

HEALTHCHECKS_ALLOW_TOOLS and HEALTHCHECKS_DENY_TOOLS take comma-separated tool names; a trailing * matches a whole family. essential is a curated preset — list_checks, get_check, list_pings, list_flips, create_check, update_check and resume_check — marked as such in the tool reference.

HEALTHCHECKS_ALLOW_TOOLS=essential
HEALTHCHECKS_ALLOW_TOOLS=list_*,get_check
HEALTHCHECKS_DENY_TOOLS=delete_check,pause_check

An entry that matches no tool aborts startup and names it, so a typo cannot silently hide a tool — an absent tool is not something anyone traces back to an environment variable. A filtered tool is never registered, so it is absent from tools/list and unknown to tools/call alike, exactly like a write tool under HEALTHCHECKS_READ_ONLY.

If you run several of these servers at once, mcp-hub is the other answer — its /hub endpoint replaces every server's tools with six meta-tools.

Installation

Claude Code

claude mcp add healthchecks-mcp -- npx -y healthchecks-mcp

Claude Desktop

{
  "mcpServers": {
    "healthchecks-mcp": {
      "command": "npx",
      "args": ["-y", "healthchecks-mcp"],
      "env": {
        "HEALTHCHECKS_API_KEY": "…"
      }
    }
  }
}

Codex

[mcp_servers.healthchecks-mcp]
command = "npx"
args = ["-y", "healthchecks-mcp"]
env = { HEALTHCHECKS_API_KEY = "…" }

Docker

docker run --rm -i \
  -e HEALTHCHECKS_API_KEY=… \
  ghcr.io/ni-c/healthchecks-mcp

Add -e HEALTHCHECKS_URL=https://hc.example.net for a self-hosted instance.

Through mcp-hub

A client that cannot spawn a local process — ChatGPT connectors, Claude on the web, Cursor, LibreChat — reaches healthchecks-mcp through mcp-hub: one container serves many stdio MCP servers over Streamable HTTP, with an OAuth 2.1 login behind a single password and long-lived tokens for the clients that cannot do OAuth. Its /hub endpoint puts every server behind six meta-tools, so one connector reaches all of them without N×tool schemas in the model's context, and it speaks both protocol revisions — a question this server asks travels through it to the person at the far end.

Its /config/mcp.json uses Claude Code's format, so the entry is the one you already have:

{
  "mcpServers": {
    "healthchecks-mcp": {
      "command": "npx",
      "args": ["-y", "healthchecks-mcp"],
      "env": {
        "HEALTHCHECKS_URL": "https://hc.example.net",
        "HEALTHCHECKS_API_KEY": "…",
        "HEALTHCHECKS_ALLOW_TOOLS": "essential"
      },
      "denyTools": ["delete_check,pause_check"]
    }
  }
}

allowTools and denyTools there are the hub's own per-server filter, which is not the same thing as *_ALLOW_TOOLS in env — the difference, and the mistake it invites, are in the client guide.

Tools