Keepitalive

Lets an AI agent read and manage your monitoring through the Model Context Protocol — "is anything down?", "why did the nightly backup fail?", "pause the staging monitors while I deploy".

It is a thin adapter over the public v1 API. Everything it can do, your API key could already do; nothing here bypasses a scope.

Install

Add this to your MCP client's config (Claude Desktop: claude_desktop_config.json; Claude Code: .mcp.json):

{
  "mcpServers": {
    "keepitalive": {
      "command": "npx",
      "args": ["-y", "@keepitalive/mcp"],
      "env": {
        "KEEPITALIVE_API_KEY": "kia_live_...",
        "KEEPITALIVE_MCP_MODE": "write",
        "KEEPITALIVE_MCP_TOOLS": "",
        "KEEPITALIVE_MCP_EXCLUDE_TOOLS": ""
      }
    }
  }
}

Only KEEPITALIVE_API_KEY is required; the rest are shown with their defaults so you can see what is adjustable. MODE picks how much the agent may do, and TOOLS/EXCLUDE_TOOLS narrow the surface further — all three are described under Configuration.

Create the key under Settings → API access. Grant it the narrowest set of scopes the work needs — see below.

What it exposes

One tool per v1 endpoint: monitors, checks, incidents, comments, triggers and their delivery logs, groups, status pages, notification settings, and the account activity feed.

get_api_guide is the exception: it reads the agent guide and the OpenAPI contract from the running API rather than returning anything baked in here. Those routes are public, so it needs no key and never sends one, and both documents are cached for the life of the process. Pass search to get one section — the guide is ~37KB and the contract ~164KB, so the contract is returned as an index of paths and schema names unless you ask for something specific.

The trigger tools point at it rather than restating it. Condition syntax in particular cannot be summarised safely in a tool description: the payload shape depends on the monitor type, and a path that does not exist compares as null, so a wrong one fails silently instead of erroring. A copy in this repo would go stale against the API it documents, which is the failure the proxy prevents.

Two endpoints are deliberately absent. /events is an open-ended SSE stream, which does not fit a request/response tool — poll get_status or list_open_incidents instead. Channel setup is app-only, so the notification tools here read channels and set per-monitor routing but cannot add a destination.

Rate limits

The API allows 60 requests/minute per key. A 429 is absorbed here rather than shown to the model: the server sends Retry-After, so the client waits that long and retries once. Only a repeated 429 surfaces, and its message says plainly that this is a client-side throttle rather than a problem with the monitored services — an agent that reads "rate limited" as an outage will report one.

A wait longer than 20 seconds is reported instead of slept through, so a tool call never looks like a hang.

An agent auditing a large fleet can still hit the limit: prefer get_summary and get_status, which answer fleet-wide questions in one request, over get_monitor per monitor.

Retries and idempotency

Every POST goes out with an Idempotency-Key. A key generated per request only covers a retry within that one call — if the model re-invokes a tool after a timeout, that is a new call with a new key, and the server has nothing to match it against. Pass idempotency_key explicitly and reuse the same value across the retry to get real replay: the server returns the first response instead of creating a second monitor or incident. Reusing a key with a changed payload is rejected rather than silently replayed.

Which of those actually appear is decided by four layers, each able only to remove:

1. Your key's scopes. The server reads them from /api/v1/me at startup and registers only tools the key can use. A read-only key gets a read-only server, whatever else is configured.

   It gates on effective_scopes — the granted scopes plus everything they imply — so a triggers:write key also gets the trigger read tools, matching what the API will actually authorize.

2. Mode (KEEPITALIVE_MCP_MODE) — read, write (default), or full.

3. Allowlist (KEEPITALIVE_MCP_TOOLS) — when set, only these tool names.

4. Denylist (KEEPITALIVE_MCP_EXCLUDE_TOOLS) — removed last.

The effective surface can never exceed what the key already grants, so narrowing here is extra safety rather than the only safety.

Why full is separate from write

write covers everything reversible: creating and editing monitors, pausing and resuming, opening and closing incidents, toggling triggers. The delete_* tools are withheld until you set mode=full.

A key wide enough to delete is not by itself a decision to let an agent delete — those tools remove data with no undo, and an agent reaching for one after misreading a situation is the failure worth designing against. Deleting a monitor also takes its history with it; pausing (set_monitor_active) is almost always what was actually meant.

Configuration

Variable	Default	Purpose
KEEPITALIVE_API_KEY	—	Required. Your kia_live_… key.
KEEPITALIVE_MCP_MODE	write	read, write, or full.
KEEPITALIVE_MCP_TOOLS	—	Comma-separated allowlist of tool names.
KEEPITALIVE_MCP_EXCLUDE_TOOLS	—	Comma-separated denylist.

Read-only example:

{
  "env": {
    "KEEPITALIVE_API_KEY": "kia_live_...",
    "KEEPITALIVE_MCP_MODE": "read"
  }
}

On startup the server writes its resolved plan, scopes, mode, and every withheld tool with the reason to stderr — your MCP client's log shows exactly what the agent can and cannot do.

Troubleshooting

could not reach …/me — the server checks the key before serving anything, so this is a bad or revoked key, or no route to the API. It fails at startup deliberately: a key problem discovered on the first tool call gets reported by the model as a monitoring outage.

A tool you expected is missing — read the stderr banner. It names the reason, usually a scope the key was not granted.

Development

npm install
npm test        # unit + stdio integration tests against a stub API
npm run build

The tests spawn the real server over stdio and talk to it with the MCP client, against a local stub of the API — no KEEPitALIVE instance required.

The contract

The tool schemas are checked against the API's published OpenAPI document, fetched from https://keepitalive.dev/api/openapi.json when the tests run. That is what stops this server offering a field the API would reject — the bugs that check has caught were all of that shape: a field that looked plausible and was accepted by nothing.

Because it is fetched rather than vendored, a field added or removed on the API fails the suite the same day instead of whenever someone remembers to refresh a copy. The cost is that these tests need network access.

KEEPITALIVE_CONTRACT_URL overrides the origin. It exists so a maintainer can run the suite against an API build that is not released yet — the tools and the contract have to change together, and that check is worthless if it can only ever see what is already live. It is not a way to point this server at some other service: the suite verifies the document really is the KEEPitALIVE contract and refuses anything else.