# UptimeMonitoring.com — Agent Skill File

UptimeMonitoring.com is API-first uptime monitoring for HTTP, TCP, ping, DNS, and SSL 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://uptimemonitoring.com/llms.txt)** — index of all documentation with LLM instructions
- **[/llms-full.txt](https://uptimemonitoring.com/llms-full.txt)** — all documentation pages concatenated in full
- **[openapi.yaml](https://api.uptimemonitoring.com/openapi.yaml)** — OpenAPI 3.1 specification for all REST endpoints (canonical host: `api.uptimemonitoring.com`)
- **[/docs/](https://uptimemonitoring.com/docs/)** — human + agent documentation
- **[/api-reference/](https://uptimemonitoring.com/api-reference/)** — interactive OpenAPI reference

---

## Authentication

Three patterns; pick the one that fits your context:

- `Authorization: Bearer umk_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 `umk_live_` prefix (e.g. `umk_live_abc123def456`). Create a dedicated key labeled `mcp` for agent setups. Each account supports up to 10 keys.

---

## MCP server URL + discovery

MCP endpoint: `https://api.uptimemonitoring.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 uptimemonitoring https://api.uptimemonitoring.com/mcp \
  --header "Authorization: Bearer umk_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.uptimemonitoring.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.uptimemonitoring.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
{
  "uptimemonitoring": {
    "url": "https://api.uptimemonitoring.com/mcp",
    "headers": {
      "Authorization": "Bearer umk_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": "uptimemonitoring",
  "server_url": "https://api.uptimemonitoring.com/mcp",
  "headers": {
    "Authorization": "Bearer umk_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 UptimeMonitoring integration -->

```json
{
  "type": "mcp",
  "url": "https://api.uptimemonitoring.com/mcp",
  "headers": {
    "Authorization": "Bearer umk_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.uptimemonitoring.com/mcp",
  "headers": {
    "Authorization": "Bearer umk_live_..."
  }
}
```

Replace `umk_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
# 1. Create a monitor
MONITOR=$(curl -s -X POST https://api.uptimemonitoring.com/api/v1/monitors \
  -H "Authorization: Bearer umk_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]*')

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

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

# 4. Register a webhook so future state changes push instead of poll
curl -s -X PUT https://api.uptimemonitoring.com/api/v1/monitors/$ID/webhook \
  -H "Authorization: Bearer umk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/uptime-webhook"}'
```

---

## 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** (`PUT /api/v1/monitors/{monitorID}/webhook`) for state-change notifications. 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://uptimemonitoring.com/docs/errors.md) before writing error-handling code.

---

## Support

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