Better Stack

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_application

Create a catalog relation with its primary and added attributes in one call. Add records with `upsert_catalog_records` afterwards. See `catalog_relations` for how the catalog works. Propose the relation to the user first (its name, matching, attributes and a few example records) and create it once they agree. For a relation describing services, add `Dependencies`, `Connections` and `Type` as added attributes, so the Dependencies map can draw its records. ## Rules - Name primary attributes after metadata keys incidents really carry. Check recent incidents' metadata with `incidents` and `incident` first: a key no incident carries never matches. - Reference teams, team members, escalation policies and other Better Stack objects as objects, like `{"type": "Team", "name": "Platform"}`, never as their names in text. - Never invent records. Every row comes from a source the user pointed you to (code, Terraform, Kubernetes, a Backstage catalog, the service map) or from the user. - Prefer `upsert_catalog_records` to removing records and adding them again: it keeps every record it doesn't name, while removing them all empties the relation.

create_catalog_relation

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

create_chart_alert

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_cloud_connection

Create a Better Stack Collector, the agent that collects logs, metrics and traces from a Docker host, a Docker Swarm or a Kubernetes cluster. Returns the collector details, the collector secret needed to install it, the ID of the source its data goes to, and the installation guide for its platform

create_collector

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_dashboard

Post a comment on an error so the findings land in the conversation the team reads in Better Stack. The comment is written as the user whose token made the call and marked as posted via MCP, so a team member can tell it apart from one typed in the app; a call made with an API token is attributed to the API instead. When the error is linked to a Linear issue whose integration syncs comments, the comment is posted on that issue too. Use error_comments to read the conversation back.

create_error_comment

Get a single-use URL to upload a file (a log, a screenshot, a trace) to, and attach it with a tool that takes `attachment_upload_ids`, such as `create_incident_comment`. The answer is a `curl` command that uploads the file from a shell, so this needs one: Claude Code, or claude.ai's code execution with this MCP server's domain allowed. Run the command, then pass the upload id to the tool. One file of up to 10 MB per URL, 10 upload URLs and 10 uploads a minute. The URL expires after 15 minutes, the uploaded file after a day, and only you can attach it.

create_file_upload

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_heartbeat

Create a new incident providing a summary of the issue, requester email, and other optional details. Notification channels (call, sms, email, critical_alert) all default to false, so an incident with none of them set reaches nobody unless an escalation policy handles it.

create_incident

Create a comment on an incident. To attach files, upload each one with create_file_upload first and pass the upload_id values it returns in attachment_upload_ids

create_incident_comment

Create an issue for an error in Linear, or a work item in Jira, through the team's integration and link the two. The issue gets Better Stack's standard body (error type, message, call site, stack trace, occurrence counts and a link back) and the integration's configured defaults for team or space, work type, assignee, labels and priority. Better Stack then posts every change to the error state as a comment on the issue. An error that already has an issue through the integration is reported, not duplicated; use link_error_issue to attach an issue that already exists.

create_error_issue

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_metric_expression

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_monitor

Register a release for an errors application, so it appears the moment it deploys instead of when its first error arrives. Returns the release ID, usable with remove_release

create_release

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. To set up a Better Stack Collector on Docker, Docker Swarm or Kubernetes, use create_collector instead

create_source

Create a new status page report

create_status_page_report

Create a new status update for an existing status page report

create_status_page_report_update

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

create_status_page_section

Change the settings of a Slack integration, as on Integrations › Slack › Configure. Only the parameters you pass change. channel_invitees, alert_options and status_page_update_resources replace the whole list

edit_slack_integration

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_application

Escalate an ongoing incident to a user, team, on-call calendar, escalation policy, or the whole organization. A policy brings its own notification channels; every other target needs at least one of call, sms, email, push or critical_alert.

escalate_incident

Execute a ClickHouse SQL query to retrieve logs, traces/spans, errors, and metrics from telemetry data. Write the query as a template and the server builds the collections for you, as Better Stack's dashboards and AI SRE do: - `FROM {{source}}` reads the source's recent and historical rows of `source_type` together (for metrics, its metrics collection), scoped to the source - `{{start_time}}` and `{{end_time}}` are the `start_time` and `end_time` arguments, e.g. `WHERE dt >= {{start_time}} AND dt < {{end_time}}` - `{{time}}` buckets `dt` to an interval that suits the range (`toStartOfInterval(dt, INTERVAL '<n> second')`); `{{interval_seconds}}` is that interval A template needs `source_type`, `start_time` and `end_time`, and no `table`. A query without `{{...}}` runs exactly as written, needs `table` and must name its `remote(...)` and `s3Cluster(...)` collections itself. - **IMPORTANT**: Use `query_help` to get instructions on how to create the correct query for logs and spans - **IMPORTANT**: Use `errors_query_help` to get instructions on how to create the correct query for errors - **IMPORTANT**: Use `metrics_query_help` to get instructions on how to create the correct query for metrics - Before a query over more than a few hours of logs, spans or other events, call `query_windows` with the same arguments: it says whether the range fits one call and, if not, the time windows that do. A template of either shape below needs no such call: `query` splits its range itself - A template listing the newest rows (`ORDER BY dt DESC LIMIT n`, filtered by `dt >= {{start_time}} AND dt < {{end_time}}`, with no aggregate, `GROUP BY`, `DISTINCT` or subquery) whose range is too wide for one call is read one time window at a time, newest first, until it has its n rows; the result says how far it read and where to continue - A template that only adds up or combines (`count()`, `countIf()`, `sum()`, `sumIf()`, `min()`, `max()`, beside the `GROUP BY` columns it selects; `ORDER BY` and `LIMIT` on those), filtered by `dt >= {{start_time}} AND dt < {{end_time}}`, with no `HAVING`, `DISTINCT` or subquery, whose range is too wide for one call but holds at most 300,000,000 rows is run in time windows, several at once, and the windows' rows merged; the result says how far it read

query

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

export_dashboard

Get every setting of a Slack integration: notification type, channel invitees, who Slack users can alert, and the notification options

slack_integration

Get comprehensive details of a specific application including its configuration, VRL transformations (the exception grouping program among them), retention settings, ingestion details, custom bucket settings (if configured)

application

Get available escalation policies for an incident

available_incident_escalation_policies

Show one catalog relation with its records, one column per attribute, paginated. Objects read as `Platform (Team 123)`, so a record can name them again by `name` or `item_id`. See `catalog_relations` for how the catalog works.

catalog_relation

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

chart_alert

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

chart_alert_help

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

chart_building_help

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

chart

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

dashboard

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

dashboard_query_help

Read the conversation on an error: comments left in the app, comments posted by an agent over MCP, replies written in the error Slack thread, and comments synced in from a linked Linear issue. Every entry names its author and, when it did not come from the app, how it was posted; a comment left on one occurrence of the error names that event.

error_comments

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

error

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

errors_query_help

Get detailed information about a specific escalation policy

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

exploration

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

explore_logs_query_help