Better Stack MCP

Acknowledge an ongoing incident

Add a new chart to a dashboard. Use the `section` parameter to organize charts into named sections — sections are auto-created if they don't exist, and charts are auto-positioned within them. **REQUIRED**: the `query`'s FROM must reference a source, either `{{source}}` or a source-type variable defined via `set_dashboard_variable` (e.g. `{{redis_source}}`). A query with no source is rejected with guidance to define it first. Dashboard chart queries run against the metrics collection: use `sum(logs_count)` (or the matching `sum(<row_type>_count)` for the source), `avgMerge(value_avg)`, `label('tag')`. Do NOT use `JSONExtract(raw, …)` — that is for live-tail charts and `query` only; dashboards have no `raw` column. Call `metrics_query_help` with the source ID **and `context: 'chart_query'`** for available metrics/labels and chart-query-style examples. **Workflow:** 1. Call `chart_building_help` for chart types, units, and settings. 2. Call `metrics_query_help` with `context: 'chart_query'` to see the source's metrics schema and chart-query examples. 3. Verify the query with `render_chart` (runs it and surfaces errors automatically) or with `query`. Use `{{source}}`, `{{start_time}}`, `{{end_time}}`, `{{time}}` variables for integration with dashboard filters. Queries can also reference custom dashboard variables — `{{var}}` (required) or `[[ AND col = {{var}} ]]` (optional clause, dropped while the variable is empty); define them with `set_dashboard_variable`.

Add a section divider to a dashboard. Sections span the full width and help organize charts into groups. Charts and sections at or below the insertion point are shifted down to make room

Get comprehensive details of a specific application including its configuration, retention settings, ingestion details, custom bucket settings (if configured)

List all available applications in a paginated table format. Returns application ID, name, platform type, team, status (active/paused), data region, and creation date

Get available escalation policies for an incident

Change a team member's role. Identify the member by `email` or `user_id` (from team_members) and pass the target `role_id` (from team_roles). The admin role cannot be assigned, and an existing admin's role cannot be changed, via the API. Pending invitations can't have their role changed — cancel and re-invite instead. If the token can reach more than one team, pass `team_id` (or `team_name`).

Get detailed information about a specific chart including its SQL queries, configuration, and settings. Use dashboard first to find the chart ID

Get detailed information about a specific chart alert including its configuration, SQL queries, status, and current incident info. Use chart_alerts first to find the alert ID

Get instructions for creating and configuring chart alerts, including alert types, operators, configuration fields, supported chart types, and common mistakes. Call this before creating or editing chart alerts

List chart alerts with optional filtering by team, chart, or dashboard. Returns alert ID, name, type, chart, dashboard, and status

Get comprehensive instructions for building charts and dashboards, including chart types, units, axis settings, column mapping, legend placement, layout tips, and common mistakes. Call this before creating or editing charts

List all available storage clusters for a specific team. Returns a table with cluster IDs, names, and regions. Used primarily for creating cloud connections to query logs and metrics data directly via ClickHouse

Create a new application in Better Stack. Returns the created application details including ID, ingestion token, ingesting host URL, retention settings, and platform-specific integration documentation links with next steps for configuration

Create a new chart alert on an existing chart. The chart must support alerts (line_chart, bar_chart, number_chart, or tail_chart with time variables). Call chart_alert_help for configuration reference. Use chart or dashboard first to find the chart ID

Create a secure cloud connection for direct ClickHouse query access to logs, spans, and metrics data. Returns connection credentials (host, port, username, password), sample queries for each data type, and cURL command examples. Connections expire after 1 hour by default

Create a new dashboard. Optionally use a template to start with pre-configured charts. Call chart_building_help for guidance on dashboard structure and layout. Optionally specify a source_id to preconfigure the dashboard with that source. Returns the new dashboard ID which can be used with add_chart_to_dashboard to add charts

Create a new heartbeat that expects a periodic request from a cron job, worker, or other background task, and alerts when that request stops arriving. Provide a `name` for the heartbeat. The heartbeat reports down once no request is received within `period` seconds plus the `grace` window. Use the returned heartbeat URL as the endpoint your job pings on every successful run.

Create a new incident providing a summary of the issue, requester email, and other optional details

Create a comment on an incident

Create a new metric expression (extract-metrics-from-logs rule) on a source. `sql_expression` runs against each log row; log fields live inside the `raw` JSON column — use `JSONExtract(raw, 'path', 'Nullable(Type)')`. The `Nullable(...)` wrapper is required. Nested paths use positional args: `JSONExtract(raw, 'request', 'headers', 'user-agent', 'Nullable(String)')`. Call `source_fields` to see what fields exist. Pass `aggregations` (e.g. `["avg", "count"]`) for an aggregated metric, or omit / pass `[]` for a label (group-by column). Prefer `build_type: new_data` (default). `historical_logs` re-runs the rule over every stored log — expensive; only when the user explicitly asks.

Create a new monitor that tracks the availability of a website, host, or service. Provide the `url` to monitor. For ping, TCP, UDP, SMTP, POP, IMAP, and DNS monitors this is the host (e.g. `example.com`) rather than a full URL. The monitor starts checking immediately unless `paused` is set to true.

Create a new log source in Better Stack. Returns the created source details including ID, ingestion token, ingesting host URL, retention settings, and platform-specific integration documentation links with next steps for configuration

Create a new status page report

Create a new status update for an existing status page report

Add a resource (monitor, heartbeat, or group) to a status page. Provide the `resource_type` and `resource_id` of the thing to display, plus a `public_name` shown to visitors (usually the resource's own name). Use `status_page_sections` to find the section to place it in; when omitted the resource is added to the status page's first section.

Create a section (resource group) on a status page to group resources under a heading

Get detailed information about a specific dashboard including its charts, sections, layout, template variables, and configuration. Use this to understand a dashboard structure before modifying it

Get instructions for writing a ClickHouse query to use inside a Better Stack **Dashboard** chart (or chart alert). The query uses template variables (`{{source}}`, `{{time}}`, `{{start_time}}`, `{{end_time}}`) and runs against the source's metrics collection — it is meant to be saved as a dashboard chart via `add_chart_to_dashboard` / `edit_chart`, NOT run directly. To instead write an ad-hoc query you will run directly via `query` or `render_chart`, use `metrics_query_help`.

List all available dashboards in a paginated table format. Returns dashboard ID, name, creation date, and last updated date

List all available dashboard templates in a paginated table format. Returns template ID, name, description, and other metadata

List all available data regions and clusters for application and source creation. Returns a table with region IDs (to use when creating applications or sources), display names, types (Region or Cluster), and geographical locations. Includes usage instructions for both standard regions and custom clusters

Delete a chart alert permanently. This will also clean up any associated incidents and anomaly models. This action cannot be undone. Use chart_alerts or chart_alert first to find the alert ID

Delete a metric expression from a source. This action cannot be undone. Call `metric_expressions` first to get the ID. `build_type: new_data` (default) stops the rule from applying to future logs but leaves already-extracted data. `build_type: historical_logs` also rebuilds the source's metrics without this rule — expensive.

Search for relevant documentation articles and return their contents

Edit an existing application in Better Stack - rename it, pause or resume ingesting, or set its VRL transformations, including the exception grouping program. Only provide the fields you want to change. Use applications or application first to find the application ID.

Edit an existing chart name, query, type, or settings. Only provide the fields you want to change. **If changing the query:** the new query's FROM must reference a source, either `{{source}}` or a source-type variable defined via `set_dashboard_variable` (queries with no source are rejected). Dashboard chart queries run against the metrics collection: use `sum(logs_count)` (or the matching `sum(<row_type>_count)` for the source), `avgMerge(value_avg)`, `label('tag')`. `JSONExtract(raw, …)` only works in live-tail charts — dashboards have no `raw` column. Verify the new query with `render_chart` (runs it and surfaces errors automatically) or with `query` before saving. Queries can also reference custom dashboard variables — `{{var}}` (required) or `[[ AND col = {{var}} ]]` (optional clause, dropped while the variable is empty); define them with `set_dashboard_variable`. Call `chart_building_help` for chart/settings reference and `metrics_query_help` with `context: 'chart_query'` for the source's metrics schema and chart-query-style examples. Use `dashboard` first to find the chart ID.

Edit an existing chart alert configuration. Only provide the fields you want to change. Call chart_alert_help for configuration reference. Use chart_alerts or chart_alert first to find the alert ID

Edit an existing dashboard's name or source eligibility. Only provide the fields you want to change. Use dashboard first to find the dashboard ID.

Edit an existing dashboard section. Only provide the fields you want to change. Use dashboard first to find the section ID

Get comprehensive details of a specific error including its type, message, call site information, first occurrence, current state (unhandled, unresolved, ignored, resolved, or reoccurred), and linked Linear/Jira issues

List error patterns for an application with occurrence counts, affected users, current state, and links. Defaults to unresolved errors and supports filtering by state. For specialized error analytics or custom SQL, use errors_query_help instead.

Get comprehensive instructions for building SQL ClickHouse queries for error tracking, including both error patterns (metrics) and individual exceptions. Explains when to use each source and provides examples for common use cases

Escalate an ongoing incident to a user, team, schedule, or policy

List all escalation policies with their steps and configuration

Get detailed information about a specific escalation policy

Get detailed information about a specific exploration (saved Explore query) including its sources, chart type, template variables, saved time range, and query. Use this to understand an exploration before modifying its source or variables

List saved explorations (saved Explore queries) in a paginated table. Returns exploration ID, name, chart type, sources, group, and last updated date. Use this to discover explorations before viewing or modifying one

Get instructions for writing a ClickHouse query to use inside the Better Stack **Explore logs** page (and live-tail charts) for log and span data. The query uses template variables (`{{source}}`, `{{time}}`, `{{start_time}}`, `{{end_time}}`) and reads fields from the `raw` JSON column — it is meant to be used in the Explore UI, NOT run directly. To instead write an ad-hoc logs/spans query you will run directly via `query`, use `query_help`.

Export a dashboard configuration as JSON. Returns the complete dashboard data structure including charts, sections, presets, and settings

Get details of a specific heartbeat

Get availability summary for a specific heartbeat

List all heartbeats with filtering and pagination options

Import a dashboard from JSON configuration. Creates a new dashboard with the provided data structure

Get detailed information about a specific incident

Get comments for an incident

List incidents with filtering and pagination options

Get the timeline of events for an incident

Invite someone to a Better Stack team by e-mail address. Optionally set their role by system-role name (`role`: responder, member, team_lead, billing_admin) or by `role_id` (use team_roles to look up ids). Defaults to responder. The admin role cannot be assigned via the API. Someone who already belongs to the organization is added to the team directly, with no invitation to accept; an organization-wide role they hold (Admin, Billing admin) is kept. If the token can reach more than one team, pass `team_id` (or `team_name`).

Get comprehensive details about a specific metric. Returns metric overview (data points, active series, available aggregations), definition (SQL expression or JSON path), example queries for different aggregation functions, and Prometheus tags (for pure metrics). Essential for understanding how to query and use a metric