MCP Reference

StatiBeat exposes two MCP surfaces. Hosted MCP is the customer-facing remote connector with OAuth consent and revoke controls. The page MCP server is a stdio server for one scoped page, backed by a StatiBeat API token.

Use this page as the feature inventory for the current MCP surfaces. For setup steps and rollout guidance, start with Hosted MCP.

note

Hosted MCP is the supported customer connector. Page MCP server details are included for trusted page-scoped automation and support workflows that can be governed with API-token policy.

Surface comparison

Capability	Hosted MCP	Page MCP server
Client shape	Remote HTTP MCP clients	Stdio MCP clients
Auth	StatiBeat OAuth consent and connector tokens	STATIBEAT_API_TOKEN
Page model	Multi-page discovery, explicit page_id for page-bound operations	One configured page or host-resolved page
User attribution	Signed-in StatiBeat user plus client identity	API token principal, with optional trusted Slack actor context for server-side Slack use
Revoke path	Product UI revokes approved connector grants and active tokens	Rotate or revoke the API token
Write boundary	Narrow incident and maintenance creation/update tools	Broader operational incident, maintenance, and Beat action tools

Hosted MCP endpoint and OAuth discovery

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

• /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. Redirect URIs must be https, except that http is accepted for loopback hosts such as localhost or another loopback address, and redirect URIs must not include fragments.

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

Hosted MCP resources

Hosted MCP always exposes the current connector session resource:

• statibeat://me

With mcp.pages.read, it also exposes:

• 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

With mcp.incidents.read, it exposes:

• 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, it exposes:

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

With mcp.analytics.read, it exposes:

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

With mcp.beats.read, it exposes:

• 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.

Hosted MCP scopes and page permissions

OAuth scope approval does not override the user's existing StatiBeat permissions.

OAuth scope	Page permission requirement
mcp.pages.read	Page read plus the relevant read permission for status definitions, lifecycle stages, maintenance lifecycle stages, or hierarchy reads
mcp.incidents.read	Incident read
mcp.incidents.write	Incident manage
mcp.maintenances.read	Maintenance read
mcp.maintenances.write	Maintenance manage
mcp.analytics.read	Analytics read
mcp.beats.read	Synthetic monitor read; pending Beat actions additionally require synthetic monitor manage

Hosted MCP prompts

Hosted prompts are scope-gated. A client sees a prompt only when its granted scopes allow the resources that prompt asks the model to read.

• draft_customer_incident
• draft_incident_update
• review_existing_incident_state
• plan_maintenance_window
• summarize_current_beat_health
• investigate_beat_failure
• review_pending_beat_action

Hosted MCP tools

With mcp.incidents.write, Hosted MCP exposes:

• create_incident
• add_incident_update

With mcp.maintenances.write, it exposes:

• schedule_maintenance
• add_maintenance_update

Hosted write tools require an explicit page_id, a granted OAuth scope, and the signed-in user's existing page permission. Hosted MCP does not expose delete operations, generic update tools, incident resolve/reopen actions, Beat mutations, subscriber administration, branding changes, Terraform governance changes, or broad settings mutations.

Page MCP server setup

The page MCP server binary lives at application/backend/cmd/statibeat-page-mcp. It serves MCP over stdio and uses the same scoped /api/v1 route family as other customer automation.

Configure it with:

• STATIBEAT_BASE_URL
• STATIBEAT_API_TOKEN
• optional STATIBEAT_ORG_ID and STATIBEAT_PAGE_ID
• optional STATIBEAT_ORG_SLUG and STATIBEAT_PAGE_PUBLIC_SLUG for shared-host routing
• optional STATIBEAT_MCP_READ_ONLY=true to expose resources and prompts without write tools
• optional STATIBEAT_MCP_ALLOWED_TOOLS=create_incident,add_incident_update to publish only named tools

The equivalent flags are --base-url, --api-token, --org-id, --page-id, --org-slug, --public-slug, --read-only, and --allowed-tools.

Page MCP server resources

The page MCP server uses the single-page URI form statibeat://page/....

• statibeat://page/status-definitions
• statibeat://page/lifecycle/stages
• statibeat://page/maintenance-lifecycle/stages
• statibeat://page/summary
• statibeat://page/incidents/active
• statibeat://page/incidents/{incident_id}
• statibeat://page/incidents/{incident_id}/updates?limit={limit}
• statibeat://page/maintenances/active
• statibeat://page/maintenances/{maintenance_id}
• statibeat://page/maintenances/{maintenance_id}/updates?limit={limit}
• statibeat://page/maintenances?filter={filter}
• statibeat://page/hierarchy/tree
• statibeat://page/subscribers/summary
• statibeat://page/analytics/summary?window_days=30
• statibeat://page/analytics/summary?window_days={window_days}
• statibeat://page/embeds
• statibeat://page/beats
• statibeat://page/beats/pending-actions
• statibeat://page/beats/{monitor_id}/recent-events?limit={limit}

The maintenance filter accepts active, upcoming, past, or scheduled. Analytics windows are bounded to keep reads operational rather than archival.

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

Page MCP server prompts

• draft_customer_incident
• draft_incident_update
• edit_incident
• review_beat_action
• resolve_incident
• plan_maintenance_window
• draft_maintenance_update
• review_existing_incident_state

Page MCP server tools

Incident tools:

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

Maintenance tools:

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

Beat tools:

• run_beat
• approve_beat_action
• reject_beat_action

Use the page MCP server for trusted page-scoped automation that needs this broader tool surface. For customer-facing remote clients, prefer Hosted MCP and its narrower OAuth-governed tool set.