Better Stack API Patterns

Better Stack MCP Tools & API Patterns

Overview

Better Stack provides an official hosted MCP server at mcp.betterstack.com covering three products in one server: Uptime (monitors, on-call, incidents, status pages), Telemetry (logs, metrics, ClickHouse SQL, dashboards), and Error Tracking (exceptions, releases). When accessed through the MCP Gateway, the Bearer token is injected automatically.

Connection & Authentication

Bearer Token Auth

Better Stack authenticates using an API token passed as a Bearer token:

Header	Description
Authorization	Bearer <your-api-token>

Token Types

Token Type	Scope	Where to Generate
Global API Token	All products, all teams	Better Stack > API tokens > Global API tokens
Uptime API Token	Uptime product only, team-scoped	Better Stack > API tokens > (select team) > Uptime API tokens

Use the Global API Token for full MCP access across Uptime, Telemetry, and Error Tracking.

Environment Variables:

export BETTERSTACK_API_TOKEN="your-api-token"

IMPORTANT: Never hardcode credentials. Always use environment variables.

How the Gateway Injects Credentials

The MCP Gateway stores your token as an org credential and automatically forwards:

Authorization: Bearer <stored-api-token>

Available MCP Tools

Monitoring

Tool	Description
list_monitors	List all monitors with status and uptime metrics
get_monitor	Get monitor details (URL, threshold, check interval)
create_monitor	Create a new uptime monitor
update_monitor	Update monitor settings
delete_monitor	Delete a monitor
pause_monitor	Pause monitoring (during maintenance)
resume_monitor	Resume a paused monitor

Heartbeat Monitoring

Tool	Description
list_heartbeats	List all heartbeats
get_heartbeat	Get heartbeat details
create_heartbeat	Create a heartbeat monitor
update_heartbeat	Update heartbeat settings
delete_heartbeat	Delete a heartbeat

Incident Management

Tool	Description
list_incidents	List incidents with status filters
get_incident	Get incident details
create_incident	Create a manual incident
acknowledge_incident	Acknowledge an active incident
resolve_incident	Resolve an incident

On-Call Scheduling

Tool	Description
list_on_call_schedules	List all on-call schedules
get_on_call_schedule	Get schedule details with rotation
create_on_call_schedule	Create a new schedule
update_on_call_schedule	Update schedule settings
delete_on_call_schedule	Delete a schedule
list_schedule_policies	List escalation/notification policies

Status Pages

Tool	Description
list_status_pages	List all status pages
get_status_page	Get status page details
create_status_page	Create a new status page
update_status_page	Update status page settings
list_status_page_sections	List sections on a status page
create_status_page_incident	Post an incident update to status page

Query Execution (Telemetry / Logtail)

Tool	Description
execute_query	Run ClickHouse SQL against log/metric data
list_saved_queries	List saved query templates
get_saved_query	Get a saved query

Dashboards (Telemetry)

Tool	Description
list_dashboards	List all dashboards
get_dashboard	Get dashboard details and panels
create_dashboard	Create a new dashboard
list_dashboard_panels	List panels on a dashboard

Applications (Error Tracking)

Tool	Description
list_applications	List error tracking applications
get_application	Get application error tracking details
list_releases	List application releases
create_release	Register a new release (for error tracking)

Pagination

Better Stack uses cursor-based pagination:

Parameter	Description
per_page	Results per page (max 50)
page[after]	Cursor from previous response to fetch next page

Pattern:

1. Call tool with per_page=50
2. Check pagination.next in response -- if present, it contains the cursor URL
3. Extract the page[after] cursor and pass to the next call
4. Continue until pagination.next is null

Rate Limiting

Better Stack enforces API rate limits per token.

• HTTP 429 responses indicate rate limit exceeded
• Back off 30 seconds; retry with exponential backoff
• Batch operations where possible
• Use filters to reduce result set sizes

Error Handling

Common Error Codes

Code	Meaning	Resolution
401	Unauthorized	Verify token; check it's a Global or Uptime API token
403	Forbidden	Global token needed for Telemetry/Error Tracking
404	Not Found	Verify ID with a list call
422	Unprocessable Entity	Check required fields in the request
429	Rate Limited	Back off 30 seconds; retry
503	Service Unavailable	Check status.betterstack.com

Error Response Format

{
  "errors": [
    {
      "status": "422",
      "title": "Unprocessable Entity",
      "detail": "URL is not a valid URL"
    }
  ]
}

Best Practices

• Use Global API Token for full MCP access across all products
• Paginate large monitor lists -- large accounts can have hundreds of monitors
• Prefer ClickHouse SQL (execute_query) for log analysis over browsing
• Pause monitors during maintenance to prevent false-positive incidents
• Cache monitor and status page metadata to reduce API calls
• Handle rate limits gracefully with exponential backoff
• Log API errors with request context for debugging

Related Skills

• monitors - Uptime monitor management
• incidents - Incident lifecycle management
• status-pages - Status page management
• oncall - On-call schedules and escalations
• logging - Log management via Logtail