# Monitive — Agent Skill File

Monitive is API-first uptime monitoring for HTTP, TCP, and ping targets — built for developers, deploy pipelines, and AI agents. This file is the skill-file entry-point for AI agents: it tells you how to authenticate, install the MCP server, call the REST API, and use the available tools.

---

## Where the source-of-truth lives

- **[/llms.txt](https://monitive.com/llms.txt)** — index of all documentation with LLM instructions
- **[/llms-full.txt](https://monitive.com/llms-full.txt)** — all documentation pages concatenated in full
- **[openapi.yaml](https://api.monitive.com/openapi.yaml)** — OpenAPI 3.1 specification for all REST endpoints on the canonical `api.monitive.com` host
- **[/docs/](https://monitive.com/docs/)** — human + agent documentation
- **[/api-reference/](https://monitive.com/api-reference/)** — interactive OpenAPI reference

---

## Authentication

Three patterns; pick the one that fits your context:

- `Authorization: Bearer mk_live_…` — static API key, server-to-server, no user identity required.
- OAuth 2.1 + PKCE via `/.well-known/oauth-authorization-server` — end-user flow for MCP hosts with a browser (Claude.ai, Claude Desktop, ChatGPT). Default for new integrations.
- Dynamic Client Registration via `POST /oauth2/register` — for new MCP hosts that need their own `client_id` programmatically.

**Rule:** prefer OAuth 2.1 + PKCE unless you are a trusted server with no end user — then Bearer.

API keys use the `mk_live_` prefix (e.g. `mk_live_abc123def456`). Create a dedicated key labeled `mcp` for agent setups. Each account supports up to 10 keys.

Keys created before 17 November 2026 start `umk_live_` and keep working.

---

## MCP server URL + discovery

MCP endpoint: `https://api.monitive.com/mcp`

Discovery endpoints (RFC 8414 / MCP spec):
- `GET /.well-known/oauth-authorization-server` — OAuth server metadata
- `GET /.well-known/oauth-protected-resource/mcp` — protected resource metadata for the MCP endpoint

---

## Install in 30 seconds

### Claude Code

<!-- mirror of /docs/mcp#claude-code; update both -->

```bash
claude mcp add --transport http monitive https://api.monitive.com/mcp \
  --header "Authorization: Bearer mk_live_..."
```

For OAuth instead of an API key, omit `--header` and run `/mcp` inside Claude Code to authenticate in the browser.

[Full setup guide →](/docs/mcp#claude-code)

### Claude Desktop

<!-- mirror of /docs/mcp#claude-desktop; update both -->

```text
https://api.monitive.com/mcp
```

In Claude Desktop, go to **Settings → Connectors**, add a custom remote MCP connector, and paste the URL above. Complete the OAuth flow when prompted.

[Full setup guide →](/docs/mcp#claude-desktop)

### ChatGPT

<!-- mirror of /docs/mcp#chatgpt; update both -->

```text
https://api.monitive.com/mcp
```

In ChatGPT connector settings, import the remote MCP server using the URL above. Complete the OAuth flow when prompted.

[Full setup guide →](/docs/mcp#chatgpt)

### Cursor

<!-- mirror of /docs/mcp#cursor; update both -->

```json
{
  "monitive": {
    "url": "https://api.monitive.com/mcp",
    "headers": {
      "Authorization": "Bearer mk_live_..."
    }
  }
}
```

Add to `.cursor/mcp.json`. Cursor also supports OAuth for remote MCP servers.

[Full setup guide →](/docs/mcp#cursor)

### OpenAI Responses (API)

<!-- mirror of /docs/mcp#openai-api; update both -->

```json
{
  "type": "mcp",
  "server_label": "monitive",
  "server_url": "https://api.monitive.com/mcp",
  "headers": {
    "Authorization": "Bearer mk_live_..."
  }
}
```

Pass this object in your Responses API tool configuration.

[Full setup guide →](/docs/mcp#openai-api)

### n8n

<!-- generic MCP Client Tool node; update if n8n ships native Monitive integration -->

```json
{
  "type": "mcp",
  "url": "https://api.monitive.com/mcp",
  "headers": {
    "Authorization": "Bearer mk_live_..."
  }
}
```

Use the **MCP Client Tool** node in n8n, set transport to **Streamable HTTP**, paste the URL, and add the `Authorization` header with your API key.

[Full setup guide →](/docs/mcp)

### Generic MCP client

<!-- spec-canonical JSON for any MCP host that supports url + headers -->

```json
{
  "url": "https://api.monitive.com/mcp",
  "headers": {
    "Authorization": "Bearer mk_live_..."
  }
}
```

Replace `mk_live_...` with your API key. Any MCP host that supports Streamable HTTP transport and custom request headers can connect this way.

[Full setup guide →](/docs/mcp)

---

## Example end-to-end workflow

```bash
set -euo pipefail

# Nothing created below is safe to leave behind on a failure partway
# through — an unattached recipient is useless, and a monitor without its
# intended recipient alerts nobody. MONITOR_ID/RECIPIENT_ID start empty so
# cleanup only ever deletes what this run actually created, and the EXIT
# trap fires on *any* exit (including `set -e` aborting on the first
# failed command), not just an explicit `exit`. It's disarmed with
# `trap - EXIT` only after the final attachment is re-read and confirmed —
# until then, a rerun after a failure starts clean instead of piling up
# orphaned monitors and recipients from each failed attempt.
MONITOR_ID=""
RECIPIENT_ID=""
cleanup() {
  local status=$?
  if [ -n "$RECIPIENT_ID" ]; then
    curl -s -X DELETE "https://api.monitive.com/api/v1/recipients/$RECIPIENT_ID" \
      -H "Authorization: Bearer mk_live_..." >/dev/null || true
  fi
  if [ -n "$MONITOR_ID" ]; then
    curl -s -X DELETE "https://api.monitive.com/api/v1/monitors/$MONITOR_ID" \
      -H "Authorization: Bearer mk_live_..." >/dev/null || true
  fi
  exit "$status"
}
trap cleanup EXIT

# 1. Create a monitor
MONITOR=$(curl -s --fail-with-body -X POST https://api.monitive.com/api/v1/monitors \
  -H "Authorization: Bearer mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"healthz","url":"https://example.com/healthz","type":"http"}')
ID=$(echo "$MONITOR" | grep -o '"id":[0-9]*' | grep -o '[0-9]*')
MONITOR_ID="$ID"

# 2. Fetch current status (returns default state until first check completes)
curl -s --fail-with-body https://api.monitive.com/api/v1/monitors/$ID \
  -H "Authorization: Bearer mk_live_..."

# 3. Fetch any incidents for this monitor
curl -s --fail-with-body "https://api.monitive.com/api/v1/incidents?monitor_id=$ID" \
  -H "Authorization: Bearer mk_live_..."

# 4. Create an account-level webhook recipient so future state changes push instead of poll
RECIPIENT=$(curl -s --fail-with-body -X POST https://api.monitive.com/api/v1/recipients \
  -H "Authorization: Bearer mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"agent-webhook","type":"webhook","config":{"url":"https://example.com/uptime-webhook"}}')
RECIPIENT_ID=$(echo "$RECIPIENT" | grep -o '"id":[0-9]*' | grep -o '[0-9]*')
RECIPIENT_SECRET=$(echo "$RECIPIENT" | grep -o '"secret":"[^"]*"' | cut -d'"' -f4)
# This plaintext secret is returned only in this creation response — every
# later read of this recipient omits it. Save it to the receiver's secret
# store now (a vault write or secrets-manager call, never a log line or a
# persisted stdout capture) and do not continue this workflow until that
# save has succeeded; without it the receiver can never verify
# X-UptimeMonitoring-Signature on deliveries from this recipient.
save_webhook_secret_to_secret_store "$RECIPIENT_SECRET" # replace with your receiver's secret-store call

# 5. Read the monitor's current recipients first — PUT replaces the
#    complete set, and a brand-new monitor can already carry the
#    account's default recipients.
CURRENT=$(curl -s --fail-with-body https://api.monitive.com/api/v1/monitors/$ID/recipients \
  -H "Authorization: Bearer mk_live_...")
# -> {"recipient_ids": [10], "recipients": [{"id": 10, "grace_s": 120}]}
# -> or, for a brand-new monitor with no default recipients:
#    {"recipient_ids": [], "recipients": []}

# 6. Build the full set from what's actually attached: every existing
#    attachment plus the new recipient. Use the structured "recipients"
#    form, not "recipient_ids", and append to the .recipients array the GET
#    returned (grace_s is always 120). .recipients is already [] on a monitor
#    with no attachments, so appending to it works unchanged in that case.
#    Requires jq.
BODY=$(echo "$CURRENT" | jq --argjson new_id "$RECIPIENT_ID" \
  '{recipients: (.recipients + [{id: $new_id, grace_s: 120}])}')
curl -s --fail-with-body -X PUT https://api.monitive.com/api/v1/monitors/$ID/recipients \
  -H "Authorization: Bearer mk_live_..." \
  -H "Content-Type: application/json" \
  -d "$BODY"

# 7. Re-read and confirm the new recipient actually landed before trusting
#    this run — the PUT above succeeding only means the API accepted the
#    request, not that this exact attachment is what's live.
FINAL=$(curl -s --fail-with-body https://api.monitive.com/api/v1/monitors/$ID/recipients \
  -H "Authorization: Bearer mk_live_...")
if ! echo "$FINAL" | grep -q "\"id\": $RECIPIENT_ID"; then
  echo "recipient $RECIPIENT_ID is not attached to monitor $ID after PUT" >&2
  exit 1
fi

# Only now disarm cleanup — the monitor and recipient are confirmed live
# and attached, so an EXIT past this point must not delete them.
trap - EXIT
```

**This read-then-write sequence has no concurrency protection.** The `PUT` carries no version, ETag, or `If-Match` precondition — two clients that each read the same list and submit their own addition can race, and whichever `PUT` lands second silently overwrites the first. Edit a monitor's recipients from one place at a time, and re-read the result after saving to confirm it matches what you intended.

See the [recipient guide](/docs/guides/alert-recipients#create-an-account-level-recipient) for the reusable, account-level recipient model and the deprecated per-monitor alternative.

---

## Tool reference

| Tool | Description | Notes |
|------|-------------|-------|
| `list_monitors` | List all monitors with current status | read-only |
| `get_monitor` | Get monitor details + recent evidence | read-only |
| `create_monitor` | Create a new monitor | — |
| `update_monitor` | Update monitor configuration | — |
| `delete_monitor` | Delete a monitor | destructive |
| `list_incidents` | Query incidents with filtering | read-only |
| `assert_monitor_healthy` | Check monitor health (deploy gates) | read-only |
| `get_account_status` | Usage against caps | read-only |

Tools are annotated with MCP hints: `readOnlyHint: true` on the read-only tools above; `destructiveHint: true` on `delete_monitor`; `idempotentHint: true` on `delete_monitor` (repeating the call after the monitor is gone produces the same result); `openWorldHint: true` on all tools (all make external API calls).

---

## LLM instructions

- **Default to OAuth 2.1 + PKCE** for any new integration. Use a static Bearer token only for trusted server-to-server contexts with no end user.
- **Prefer webhooks** for state-change notifications: create an account-level webhook recipient with `POST /api/v1/recipients` and attach it with `PUT /api/v1/monitors/{monitorID}/recipients` — see the [recipient guide](/docs/guides/alert-recipients#create-an-account-level-recipient). Never poll `/api/v1/monitors/{monitorID}` in a tight loop.
- **Always include `User-Agent`** identifying your client (e.g. `MyApp/1.2.3 (mcp-via-claude)`). Helps with audit-log diagnosis and our ability to flag problematic clients. Rate limits are per-account (200/min), not per-UA.
- **Errors use a flat envelope:** `{"error":"..."}` — not RFC 7807. Match on HTTP status first, then the literal `error` string where needed. Read [`/docs/errors.md`](https://monitive.com/docs/errors.md) before writing error-handling code.

---

## Support

Questions, issues, or abuse reports: [hello@monitive.com](mailto:hello@monitive.com).
