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:
- Call tool with
per_page=50
- Check
pagination.next in response -- if present, it contains the cursor URL
- Extract the
page[after] cursor and pass to the next call
- 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
