# KEEPitALIVE MCP server

Lets an AI agent read and manage your monitoring through the
[Model Context Protocol](https://modelcontextprotocol.io) — "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`):

```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](#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:

```json
{
  "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

```sh
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.