Skip to main content

MCP Reference

StatiBeat exposes one customer MCP surface: Hosted MCP. It uses remote HTTP transport, OAuth consent, multi-page discovery, explicit page scoping, existing page permissions, audited writes, and product-managed connector revocation.

Use Hosted MCP for setup and rollout guidance.

Endpoint and OAuth discovery​

The Hosted MCP admin screen publishes the resource URL for the current environment. Clients use:

  • /mcp for JSON-RPC MCP transport
  • /.well-known/oauth-protected-resource for protected-resource metadata
  • /.well-known/oauth-authorization-server for authorization-server metadata
  • /mcp/oauth/authorize for browser authorization and consent
  • /mcp/oauth/token for authorization-code and refresh-token exchange
  • /mcp/oauth/revoke for token revocation

Authorization uses code plus PKCE S256, does not use a client secret, and supports authorization_code and refresh_token grants. Authorization codes expire after 10 minutes, access tokens after 1 hour, and refresh tokens after 30 days.

The product also uses browser-session management routes at /api/v1/admin/hosted-mcp/settings and /api/v1/admin/hosted-mcp/connections/{id}/revoke. Those are UI management endpoints, not API-token automation endpoints.

Resources​

Hosted MCP always exposes:

  • statibeat://me

With mcp.pages.read:

  • statibeat://pages
  • statibeat://pages/{page_id}/summary
  • statibeat://pages/{page_id}/status-definitions
  • statibeat://pages/{page_id}/lifecycle/stages
  • statibeat://pages/{page_id}/maintenance-lifecycle/stages
  • statibeat://pages/{page_id}/hierarchy/tree
  • statibeat://pages/{page_id}/embeds

With mcp.subscribers.read:

  • statibeat://pages/{page_id}/subscribers/summary

With mcp.incidents.read:

  • statibeat://pages/{page_id}/incidents/active
  • statibeat://pages/{page_id}/incidents/resolved?limit={limit}
  • statibeat://pages/{page_id}/incidents/{incident_id}
  • statibeat://pages/{page_id}/incidents/{incident_id}/updates?limit={limit}

With mcp.maintenances.read:

  • statibeat://pages/{page_id}/maintenances/active
  • statibeat://pages/{page_id}/maintenances/upcoming
  • statibeat://pages/{page_id}/maintenances?filter={filter}
  • statibeat://pages/{page_id}/maintenances/{maintenance_id}
  • statibeat://pages/{page_id}/maintenances/{maintenance_id}/updates?limit={limit}

The maintenance filter accepts active, upcoming, past, or scheduled.

With mcp.analytics.read:

  • statibeat://pages/{page_id}/analytics/summary?window_days={window_days}

With mcp.beats.read:

  • statibeat://pages/{page_id}/beats
  • statibeat://pages/{page_id}/beat-groups
  • statibeat://pages/{page_id}/beats/pending-actions
  • statibeat://pages/{page_id}/beats/recent-failures?limit={limit}
  • statibeat://pages/{page_id}/beats/{monitor_id}/recent-events?limit={limit}

Timeline limit parameters default to 20 and cap at 200. Analytics window_days defaults to 30 and caps at 90.

Scopes and page permissions​

OAuth scopePage permission requirement
mcp.pages.readPage read plus the relevant catalog, hierarchy, settings, or embed read permission
mcp.beats.readSynthetic monitor read; pending Beat actions additionally require synthetic monitor manage
mcp.beats.writeSynthetic monitor manage
mcp.incidents.readIncident read
mcp.incidents.writeIncident manage
mcp.maintenances.readMaintenance read
mcp.maintenances.writeMaintenance manage
mcp.analytics.readAnalytics read
mcp.subscribers.readSubscriber read

OAuth consent does not override existing StatiBeat permissions. Page-bound resources, prompts, and tools require an explicit page_id.

Prompts​

Hosted prompts are scope-gated:

  • draft_customer_incident
  • draft_incident_update
  • edit_incident
  • resolve_incident
  • review_existing_incident_state
  • plan_maintenance_window
  • draft_maintenance_update
  • summarize_current_beat_health
  • investigate_beat_failure
  • review_pending_beat_action
  • review_beat_action

Tools​

With any Hosted MCP write scope:

  • draft_change
  • validate_change
  • apply_change
  • cancel_change

The typed change workflow supports every Hosted MCP write action listed below. It validates the selected page, OAuth scope, page permission, target record, and action fields before returning a deterministic draft ID. apply_change rejects the request until the caller sends both the unchanged draft and explicit confirmation.

With mcp.incidents.write:

  • create_incident
  • backfill_incident
  • update_incident
  • add_incident_update
  • acknowledge_incident
  • resolve_incident
  • reopen_incident
  • delete_incident

With mcp.maintenances.write:

  • schedule_maintenance
  • update_maintenance
  • add_maintenance_update
  • complete_maintenance
  • cancel_maintenance
  • delete_maintenance

With mcp.beats.write:

  • run_beat
  • approve_beat_action
  • reject_beat_action

Every write tool requires an explicit page_id, the matching OAuth scope, and the signed-in user's existing page permission. Destructive tools are marked as destructive in MCP metadata, and writes carry Hosted MCP rate-limit and audit context.

backfill_incident posts a historical incident that has already been resolved. It requires the incident title, description, started_at, and resolved_at; it also accepts affected scope, acknowledged_at, and timestamped timeline updates. It writes resolved history without replaying live subscriber or Slack notifications for the past event.

Direct operational tools remain available for clients that implement their own confirmation UX. Clients without a trusted confirmation interface should use the typed change workflow.