API Reference

API: MCP server

AI agents such as Claude, Cursor and other MCP clients can manage a workspace through Beacon’s Model Context Protocol server. Every tool runs the matching REST API operation, with the same fields, plan limits, errors and audit log.

Connecting

The server speaks streamable HTTP at:

https://usebeacon.pro/mcp/beacon

Authenticate with a workspace API token as a bearer token (see Authentication). The server acts on the token’s workspace. A read-only token can only use the list and get tools.

Claude Code:

claude mcp add --transport http beacon https://usebeacon.pro/mcp/beacon \
  --header "Authorization: Bearer YOUR_API_TOKEN"

Cursor and other clients that take a JSON config:

{
  "mcpServers": {
    "beacon": {
      "type": "streamableHttp",
      "url": "https://usebeacon.pro/mcp/beacon",
      "headers": { "Authorization": "Bearer YOUR_API_TOKEN" }
    }
  }
}

How tools behave

Results are the REST API’s JSON. Lists return meta.next_cursor; pass it back as cursor for the next page.
Most tools take a status page slug as page. Start with get_workspace and list_status_pages.
Errors carry the same stable codes as the REST API, such as validation_failed, not_found, insufficient_scope, plan_limit_reached and rate_limited.
Writes are real: incidents notify subscribers, test_alert_channel sends a real message, check_monitor checks a real URL.
Rate limits are shared with the REST API.

Tools

get_workspace

The workspace this token belongs to: plan, plan limits, usage counts, read-only state and the token's scopes.

list_activity

Workspace audit log, newest first (who changed what; API changes carry via=api).

list_on_call_schedules

On-call schedules and who is on call right now.

list_escalation_policies

Escalation policies of a status page with their steps.

list_playbooks

Automation playbooks of a status page (trigger and the incident they open).

get_sla

SLA target of a status page and each monitor's uptime against it.

list_status_pages

Status pages in the workspace (slug, visibility, overall status).

get_status_page

One status page.

create_status_page

Create a status page. Counts against max_status_pages.

update_status_page

Update a status page; send only the fields to change.

delete_status_page

Delete a status page and everything on it (components, monitors, incidents, subscribers). Irreversible.

list_components

Components of a status page, in display order.

get_component

One component.

create_component

Add a component to a status page.

update_component

Update a component, e.g. set its status; status changes notify webhooks and cascade to dependents.

delete_component

Delete a component.

reorder_components

Set the display order: every component id of the page, in the new order.

list_monitors

Uptime monitors of a status page with their current state and uptime.

get_monitor

One monitor: config, state, last check result, uptime, SSL/domain expiry.

create_monitor

Create a monitor (http, heartbeat, tcp, ping, dns or browser). Counts against max_monitors_per_status_page.

update_monitor

Update a monitor; send only the fields to change. enabled=false pauses it.

delete_monitor

Delete a monitor and its check history.

check_monitor

Queue a check of the monitor now (at most once per 30 seconds per monitor). Read the result with list_monitor_checks.

list_monitor_checks

Recent check results of a monitor, newest first.

list_incidents

Incidents of a status page, newest first.

get_incident

One incident with its timeline updates.

create_incident

Open an incident. Notifies the team, subscribers, webhooks, Slack and alert channels.

update_incident

Update an incident; a message also posts a timeline update. state=resolved resolves it (see resolve_incident).

resolve_incident

Resolve an incident: restores components, releases linked monitors and notifies everyone.

post_incident_update

Post a timeline update to an incident and notify subscribers.

list_incident_updates

Timeline updates of an incident, oldest first.

delete_incident

Delete an incident and its timeline.

list_maintenances

Scheduled maintenance windows of a status page.

get_maintenance

One maintenance window.

create_maintenance

Schedule maintenance; notifies subscribers.

update_maintenance

Update a maintenance window (e.g. state in_progress, completed or cancelled).

delete_maintenance

Delete a maintenance window.

list_subscribers

Email subscribers of a status page.

get_subscriber

One subscriber.

create_subscriber

Add a subscriber; they get a double opt-in email unless confirmed=true (needs the subscribers:confirm scope).

update_subscriber

Set which components a subscriber follows (empty = all).

delete_subscriber

Remove a subscriber.

list_webhooks

Outgoing webhooks of a status page (secrets are never returned).

get_webhook

One outgoing webhook.

create_webhook

Add an outgoing webhook for incident/component events.

update_webhook

Update an outgoing webhook.

delete_webhook

Delete an outgoing webhook.

list_alert_channels

Alert channels (Slack, Discord, Teams, Telegram, webhook). Secret config is never returned; secrets_set names what is stored.

get_alert_channel

One alert channel.

create_alert_channel

Create an alert channel. Counts against max_alert_channels.

update_alert_channel

Update an alert channel; the type cannot change.

delete_alert_channel

Delete an alert channel.

test_alert_channel

Send a real test alert through the channel and report whether it was delivered (max 3 per channel per minute).