# FastMonitor setup for AI coding agents

You are a coding agent setting up FastMonitor for the user. FastMonitor checks websites, APIs and servers on a schedule, watches cron jobs and background workers, and alerts the right people when something breaks. This file is the whole setup from https://www.fastmonitor.co.uk/docs in one place. Follow the steps in order.

- Docs: https://www.fastmonitor.co.uk/docs
- Telemetry API reference: https://www.fastmonitor.co.uk/api
- This file: https://www.fastmonitor.co.uk/docs/agent-setup.md

## What you need from the user

You cannot create the account, the API key or the MCP token: the user does that in the FastMonitor dashboard and gives them to you. Ask for:

- **API origin**: the user's FastMonitor API address. The dashboard shows it with the telemetry snippet on each job monitor's page. Every `https://<your-api-origin>` below stands for it.
- **Monitor key** of each job monitor you instrument (step 1).
- **API key** with the `monitor:telemetry` scope (step 2).
- **MCP token**, only if the user wants you connected to FastMonitor (step 5).

Keep the API key and the MCP token in server-side secrets, such as environment variables or a secret manager. Never commit them, print them in logs, or put them in browser code or a `NEXT_PUBLIC_*` variable.

## 1. Create a monitor (the user, in the dashboard)

Monitors are set up in the dashboard; there is no public API for setting them up.

1. Sign in at https://www.fastmonitor.co.uk/auth/sign-in. No account yet: https://www.fastmonitor.co.uk/auth/register
2. Uptime, SSL, DNS and broken-link checks run from FastMonitor's side and need no code.
3. For a cron job or worker, add a job monitor with its schedule and grace period, and note its **monitor key**.

## 2. Create an API key (the user, in the dashboard)

In Settings → API, create a key with the `monitor:telemetry` scope. It is shown once and stored only as a hash, so keep it in a server-side secret. A key can only report for its own account's monitors. All scopes: `monitor:telemetry`, `monitor:read`, `monitor:write`, `issue:read`, `issue:write`.

## 3. Report each run of the job

Send `RUN` when the job starts, then `COMPLETE` or `FAIL` when it ends. FastMonitor opens an issue if a run fails, runs too long or never arrives.

Send this request to `https://<your-api-origin>/e/execution-events`:

```http
POST /e/execution-events
Authorization: Bearer <api-key>
Content-Type: application/json

{"monitorKey": "daily-report", "state": "RUN"}
```

The same request with curl (`$MAKI_MONITOR_API_KEY` holds the API key):

```sh
curl -X POST "https://<your-api-origin>/e/execution-events" \
  -H "Authorization: Bearer $MAKI_MONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"monitorKey": "daily-report", "state": "RUN"}'
```

Only `monitorKey` and `state` are required. Every field:

```json
{
  "monitorKey": "daily-report",
  "state": "RUN",
  "timestamp": "2026-06-13T10:00:00.000Z",
  "duration": 1234,
  "errorMessage": "optional error",
  "metadata": { "deployment": "prod", "region": "eu-west-2" },
  "idempotencyKey": "daily-report:2026-06-13T10:00:00Z:RUN"
}
```

| Field | Meaning |
| --- | --- |
| `monitorKey` | Required. The key of a job monitor. |
| `state` | Required. RUN, COMPLETE or FAIL. |
| `timestamp` | ISO 8601, UTC. Defaults to the time the request arrives. |
| `duration` | Run time in milliseconds, usually sent with COMPLETE. |
| `errorMessage` | Free text, usually sent with FAIL. |
| `metadata` | Any JSON object you want stored with the event. |
| `idempotencyKey` | A stable key per logical event. Accepted and echoed back; not yet used to drop duplicates. |

Wire it into the job:

1. Send `RUN` just before the job's work starts.
2. When the work succeeds, send `COMPLETE` with `duration` in milliseconds.
3. When it throws or exits non-zero, send `FAIL` with `errorMessage`, then let the job fail as it did before.
4. Telemetry must never break the job: give each request a timeout of a few seconds and do not let its errors escape.
5. Retry on `429`, `5xx` and network errors with exponential backoff, and send a stable `idempotencyKey` per event.

A `201` response means the event was accepted. Responses, error codes and retry rules: https://www.fastmonitor.co.uk/api#endpoint

## 4. Optional: install an SDK (publishing pending)

Publishing pending: the SDKs are not on npm, PyPI or Packagist yet, so these install commands will not work until they are published. Until then, send the HTTP request above: the SDKs send exactly that request.

| Language | Package | Install (once published) | Status |
| --- | --- | --- | --- |
| JavaScript / TypeScript | `@maki/monitor` on npm | `npm install @maki/monitor` | Publishing pending |
| Python | `makimonitor` on PyPI | `pip install makimonitor` | Publishing pending |
| PHP | `maki/monitor-php` on Packagist | `composer require maki/monitor-php` | Publishing pending |

Point the SDK at the user's API origin (its base URL setting) rather than its built-in default. Usage examples: https://www.fastmonitor.co.uk/api#sdks

## 5. Connect the agent to FastMonitor (MCP)

FastMonitor serves a remote MCP endpoint at `https://<your-api-origin>/mcp` (Streamable HTTP, `Authorization: Bearer` with an MCP token). The user creates the token in the dashboard under Settings → AI agents & MCP, with only the permissions it needs. It is shown once, next to ready-made setup with the server address filled in, and can be revoked there at any time.

### Claude Code

```sh
claude mcp add --transport http fastmonitor https://<your-api-origin>/mcp \
  --header "Authorization: Bearer mcp_xxxxxxxx"
```

### Codex

```sh
export FASTMONITOR_MCP_TOKEN=mcp_xxxxxxxx
codex mcp add fastmonitor --url https://<your-api-origin>/mcp --bearer-token-env-var FASTMONITOR_MCP_TOKEN
```

### Hermes Agent

`~/.hermes/.env`:

```sh
FASTMONITOR_MCP_URL=https://<your-api-origin>/mcp
FASTMONITOR_MCP_TOKEN=mcp_xxxxxxxx
```

`~/.hermes/config.yaml`:

```yaml
mcp_servers:
  fastmonitor:
    url: "${FASTMONITOR_MCP_URL}"
    headers:
      Authorization: "Bearer ${FASTMONITOR_MCP_TOKEN}"
```

Tools:

| Tool | Permission | Does |
| --- | --- | --- |
| `list_monitors` | Read monitors | Your monitors with type, host, current state and status. |
| `get_monitor_summary` | Read monitors | One monitor by id or key, with its last run. |
| `list_open_issues` | Read issues | Open incidents. |
| `get_issue_summary` | Read issues | One incident with its five latest updates. |
| `acknowledge_issue` | Acknowledge issues | Adds a note and moves an unresolved incident to investigating. Nothing else. |

Tokens are scoped to the user's own monitors and issues, hashed at rest, limited to 60 requests a minute and audited on every call. The Claude Code, Codex and Hermes plugins are publishing pending: they are not listed in the Claude, OpenAI or Nous plugin directories yet. The MCP setup above works without them. More: https://www.fastmonitor.co.uk/docs#agent-plugins

## Check your work

- A test `RUN` and then `COMPLETE` for the monitor key each return `201`.
- The API key and the MCP token are read from secrets, and neither is committed or printed.
- A telemetry failure cannot make the job itself fail.