# Hyperping MCP

> Hosted Model Context Protocol server for Hyperping synthetic monitoring.
> Gives AI agents read/write access to monitor state, outages, SLAs, on-call
> schedules, and notification integrations for a single Hyperping project.

## Endpoint

- URL: https://api.hyperping.io/v1/mcp
- Transport: Streamable HTTP (JSON-RPC 2.0), supports POST/GET/DELETE
- Auth: Authorization: Bearer <hyperping-api-key>
- Scope: one project per key, server-enforced and immutable

## Tools

### Read

- list_monitors(status?: 'up'|'down'|'paused'|'ssl_expiring', page?: int, limit?: int<=200) — paginated monitor list
- get_monitor(uuid) — full monitor config
- search_monitors_by_name(query) — substring match on name/URL
- get_status_summary() — counts + currently-down monitors
- list_outages(page?, search?, status?: 'all'|'ongoing'|'resolved', type?: 'all'|'manual'|'monitor')
- get_outage(uuid) — flat outage record
- get_outage_timeline(uuid) — structured events: outage_detected, cross_region_verification, outage_verified, alerts_dispatched, acknowledged, service_restored
- get_monitor_outages(monitor_uuid, page?, status?)
- list_recent_alerts(from?, to?, resolution?: 'hour'|'day'|'week'|'month', monitor_uuids?)
- get_monitor_uptime(from?, to?, resolution?, monitor_uuids?) — SLA % (project and per-monitor)
- get_monitor_response_time(from?, to?, resolution?, monitor_uuids?)
- get_monitor_mttr(from?, to?, monitor_uuids?)
- get_monitor_mtta(from?, to?, monitor_uuids?)
- get_monitor_anomalies(uuid)
- get_monitor_http_logs(uuid, page?, limit?<=200, level?: ('info'|'warn'|'error')[])
- list_on_call_schedules() — includes current on-call per schedule
- get_on_call_schedule(uuid)
- list_escalation_policies()
- get_escalation_policy(uuid) — reveals linked schedule UUIDs
- list_team_members() — user id → name/email
- list_integrations() — Slack, Telegram, Discord, PagerDuty, OpsGenie, Teams, Google Chat, webhook, email, JSM, …
- get_integration(uuid)

### Write (requires read_write key)

- create_monitor(name, url, protocol?, port?, http_method?, regions?, check_frequency?, timeout?, expected_status_code?, request_body?, request_headers?, required_keyword?, paused?, alerts_wait?, dns_*?, escalation_policy?, group_id?)
- update_monitor(uuid, ...partial) — partial patch
- pause_monitor(uuid) — equivalent to update_monitor(uuid, paused=true)
- resume_monitor(uuid) — equivalent to update_monitor(uuid, paused=false)

### Intentionally absent

- No delete tool — use the dashboard or REST API. Pause instead.
- No billing, no API-key CRUD, no SSO, no teammate invites.
- No status-page incident management.

## Common query patterns

### "Who's on-call for monitor X right now?"

1. get_monitor(uuid) → read escalation_policy.uuid
2. get_escalation_policy(that uuid) → find linked schedule UUIDs
3. get_on_call_schedule(that uuid) → current on-call user ID
4. list_team_members() → resolve ID to name/email

### "What broke in the last 7 days?"

1. list_outages({ status: 'all', page: 0 }) — 20/page, paginate via hasNextPage
2. For each interesting outage: get_outage_timeline(uuid) for full context

### "Worst SLA this month?"

1. get_monitor_uptime({ from: ISO_30d_ago, to: ISO_now })
2. Sort the returned monitors[] array by averageUptime ascending; first element is the worst.

### "Everything with SSL expiring soon?"

1. list_monitors({ status: 'ssl_expiring' }) — filters to monitors with 0–30 days left

## Response shapes

- Every tool returns an MCP content block with type: "text" containing pretty-printed JSON.
- List tools return { <resource>: [...], total, page, resultsPerPage, hasNextPage }.
- Single-item tools return the resource object directly.
- Errors surface via MCP isError: true with a human-readable message (e.g., "This API key is read-only.", "Monitor not found").

## Security & safety

- API keys are 1:1 with projects; server-side enforcement, cannot be overridden.
- read_only keys cannot invoke write tools.
- Deactivated keys fail immediately on next call.
- No cross-project data access is possible, even with a crafted monitor UUID.

## Rate limits

- Same limiter as the REST API. Expect 4xx on burst traffic.
- Prefer narrow date windows on reporting tools — 90-day windows can return 100KB+.