MCP server

Connect AI assistants to your Uptime and Telemetry data through the Model Context Protocol.

Getting started

If this is your first time working with MCP servers, check out our MCP explained guide to understand the basics.

Step 1: Install the MCP server

The Better Stack MCP server runs as a remote HTTP server. Add one of the following configurations to your MCP client:

OAuth (recommended)

If your client supports OAuth, use this minimal configuration and sign in through the browser when prompted:

{
  "mcpServers": {
    "betterstack": {
      "type": "http",
      "url": "https://mcp.betterstack.com"
    }
  }
}

If you're using Claude Code, you can add the server directly from the CLI:

claude mcp add betterstack --transport http https://mcp.betterstack.com

API token

For clients that support HTTP servers but not OAuth, pass your API token via the Authorization header:

{
  "mcpServers": {
    "betterstack": {
      "type": "http",
      "url": "https://mcp.betterstack.com",
      "headers": {
        "Authorization": "Bearer $TOKEN"
      }
    }
  }
}

Proxy (mcp-remote)

If your MCP client doesn't support remote HTTP servers, you can use the mcp-remote proxy instead:

{
  "mcpServers": {
    "betterstack": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.betterstack.com",
        "--header",
        "Authorization: Bearer ${BETTERSTACK_API_TOKEN}"
      ],
      "env": {
        "BETTERSTACK_API_TOKEN": "$TOKEN"
      }
    }
  }
}

Step 2: Test your connection

Your AI assistant can now access Better Stack data. Try these:

• "Show me the current status of all monitors"
• "What's the availability of my website monitor?"
• "What incidents occurred yesterday?"
• "What metrics are available for my source?"
• "Build an explore query to find HTTP 500 errors"
• "Create a dashboard showing error rates for my API service"

Limiting available tools

By default, the Better Stack MCP server exposes all available tools to your AI assistant. You can restrict which tools are available by passing a custom header in your MCP configuration.

• X-MCP-Tools-Only: Allowlist - only the specified tools will be available
• X-MCP-Tools-Except: Blocklist - all tools except the specified ones will be available

Include only specific tools

{
  "mcpServers": {
    "betterstack": {
      "type": "http",
      "url": "https://mcp.betterstack.com",
      "headers": {
        "Authorization": "Bearer $TOKEN",
        "X-MCP-Tools-Only": "monitors,monitor,incidents"
      }
    }
  }
}

Exclude specific tools

{
  "mcpServers": {
    "betterstack": {
      "type": "http",
      "url": "https://mcp.betterstack.com",
      "headers": {
        "Authorization": "Bearer $TOKEN",
        "X-MCP-Tools-Except": "remove_dashboard,remove_chart"
      }
    }
  }
}

This is useful when you want to give your AI assistant read-only access, limit it to a specific workflow, or reduce the initial context size when you only need a subset of tools.

Documentation tools

Your AI assistant can search Better Stack documentation and pull relevant articles directly into the conversation:

• Search documentation: Searches Better Stack documentation and returns the contents of relevant articles

Example queries

• "How do I forward logs from Kubernetes to Better Stack?"
• "Look up the Better Stack docs for the Terraform provider"

Uptime tools

Your AI assistant can manage monitoring infrastructure and incidents through natural language. Ask questions like:

• "Show me all monitors that are currently down"
• "What's the availability of my website this month?"
• "Create an incident for the payment service outage"
• "Who's on-call right now?"
• "Acknowledge incident #1234 and add a comment about the fix"

On-call scheduling and alerting

Find who's on-call and understand escalation policies.

On-call scheduling

• Get on-call details: Shows who's currently on-call across all schedules
• List on-call calendars: Provides information about on-call calendars and rotations
• List on-call events: Lists upcoming shifts and schedule changes
• Get on-call event details: Fetches details for specific on-call events
• Get on-call rotation details: Explains how rotations are configured

Example queries

• "Who's on-call right now?"
• "Show me the on-call schedule for next week"
• "What are the rotation details for our main on-call calendar?"

Escalation policies

• Get available incident escalation policies: Shows available escalation targets for incidents
• List escalation policies: Lists configured escalation rules and steps
• Get escalation policy details: Provides detailed policy information
• List severities: Shows incident severity levels and configurations
• Get severity details: Explains specific severity settings

Example queries

• "Show me escalation options for incident #5678"
• "List all escalation policies and their steps"
• "What are the notification settings for critical severity incidents?"

Incidents

Create, manage, and collaborate on incidents from start to resolution.

• Create incident: Reports new issues with context and metadata
• List incidents: Finds incidents by date, status, monitor, or other criteria
• Get incident details: Shows full incident information including error messages and screenshots
• Get incident timeline: Displays complete incident history
• Get incident comments: Retrieves incident comments
• Create incident comment: Adds team collaboration comments
• Acknowledge incident: Takes ownership of incidents to stop escalations
• Escalate incident: Routes incidents to users, teams, schedules, or policies
• Resolve incident: Marks incidents as fixed
• Reopen incident: Reopens a resolved incident within 24 hours of resolution

Example queries

• "List all unacknowledged incidents from today"
• "Create an incident for the payment service outage with high severity"
• "Acknowledge incident #1234 and add a comment about the database fix"
• "Show me the timeline for the last critical incident"
• "Reopen incident #1234, the issue is happening again"

Monitoring

Check service health through monitors and heartbeats.

Monitors

• List monitors: Shows all monitors with filtering options
• Get monitor details: Provides monitor configuration, status, and settings
• Create monitor: Creates a new monitor to track the availability of a website, host, or service
• Get monitor availability: Calculates SLA summaries and uptime percentages
• Get monitor response times: Analyzes performance metrics and trends

Example queries

• "Show me all monitors that are currently down"
• "What's the availability of my website monitor this month?"
• "List monitors with response times above 5 seconds"
• "Create a monitor for https://example.com and check it every 30 seconds"

Heartbeats

• List heartbeats: Shows all heartbeat monitors and their status
• Get heartbeat details: Provides heartbeat configuration and recent activity
• Create heartbeat: Creates a new heartbeat that alerts when a cron job or background task stops reporting
• Get heartbeat availability: Tracks uptime for scheduled tasks

Example queries

• "List all heartbeats that are currently down"
• "Show me the status of my database backup heartbeat"
• "What's the uptime of my daily cleanup job this week?"
• "Create a heartbeat for my nightly database backup job"

Status pages

Communicate service status and maintenance to users.

• List status pages: Shows all public status pages
• Get status page details: Provides status page configuration and current status
• Update status page: Updates status page settings like company name, theme, layout, or custom domain
• Get status page resources: Lists monitors and heartbeats displayed on each page
• Add status page resource: Adds a monitor, heartbeat, or group to a status page
• Update status page resource: Changes a resource's public name, description, widget type, or placement
• Remove status page resource: Removes a resource from a status page
• Get status page sections: Lists the sections of a status page
• Create status page section: Creates a section to group status page resources under a heading
• Update status page section: Renames a section or moves it to a new position
• Remove status page section: Removes a section and its resources from a status page
• Create status page report: Creates incident reports or maintenance announcements
• Create status page report update: Adds updates to ongoing reports
• List status page reports: Shows status reports for a specific page
• List status page report updates: Lists updates for a specific report
• Get status page report update details: Provides details for specific updates

Example queries

• "Show me all status pages and their current status"
• "Create a status page report for scheduled database maintenance tomorrow"
• "List all recent reports on our main status page"
• "Update the maintenance report with completion status"
• "Add my API monitor to the status page under a new 'Core services' section"
• "Switch my status page to the dark theme"

Telemetry tools

Your AI assistant can analyze logs, query metrics, and manage observability infrastructure through natural language. Ask questions like:

• "Show me all error logs from the past hour"
• "Create a new log source for my Node.js application"
• "What metrics are available for my production source?"
• "Build a query to find HTTP 500 errors in my API logs"
• "Get field details for my application logs"

Query your logs, traces, errors & metrics

You can execute ClickHouse queries directly against your Better Stack data. Use the instruction tools (Get query instructions, Get metric query instructions, Get errors query instructions, Get replays query instructions) to learn how to write queries for each data type, then run them with Execute query.

• Execute query: Executes a ClickHouse SQL query against your telemetry data — works with logs, spans, metrics, exceptions, and replays
• Render chart: Executes a ClickHouse SQL query and renders the result as a line, bar, or pie chart — useful for visualizing trends over time directly in the conversation

Example queries

• "Run a query to get the top 10 error messages from today"
• "Execute this ClickHouse query against my production logs"
• "Query my metrics source for average response times over the last hour"
• "Run a query to find exception counts grouped by release version"
• "Show me a chart of error rates per minute for the last 24 hours"
• "Visualize HTTP 500 error counts over time as a chart"

Sources

Manage log sources and explore data structure.

Source management

• List sources: Shows all log sources with status and configuration
• Get source details: Provides detailed source configuration and settings
• Create source: Creates new log sources with integration guides
• Get source fields: Discovers available fields for querying logs and spans

Example queries

• "List all my log sources and their current status"
• "Create a new Docker log source in the US East region"
• "Show me all available fields for my application source"
• "Get details for source #1234 including ingestion settings"

Dashboards

Manage and interact with your observability dashboards.

Dashboard management

• List dashboards: Lists all dashboards with their ID, name, creation, and update dates
• Get dashboard details: Shows detailed dashboard information including charts, sections, layout, and configuration
• List dashboard templates: Lists all available dashboard templates, including ID, name, description, and platform
• Create dashboard: Creates a new dashboard, optionally from a template or with a specific source
• Configure dashboard: Updates a dashboard's name or source eligibility
• Export dashboard: Exports a dashboard's full configuration, including charts, sections, and settings, as JSON
• Import dashboard: Imports a new dashboard from a JSON configuration, creating a new dashboard with the provided data structure
• Remove dashboard: Permanently removes a dashboard and all its associated charts

Example queries

• "List all my dashboards"
• "Show me the details for dashboard #1234"
• "Create a new dashboard from the Nginx template"
• "Rename dashboard #1234 to 'Production Overview'"
• "Export dashboard #1234 as JSON"
• "Import a new dashboard using the provided JSON data"
• "Remove dashboard #5678"

Charts

• Get chart details: Shows chart configuration, SQL queries, and settings
• Get chart building instructions: Provides guidance on chart types, units, axis settings, and best practices
• Get dashboard query instructions: Provides instructions for writing ClickHouse queries used inside dashboard charts
• Add chart to dashboard: Adds a new chart with a SQL query to a dashboard
• Configure chart: Updates a chart's name, type, query, or settings
• Remove chart: Permanently removes a chart from its dashboard
• Add dashboard section: Adds a section divider to organize charts into groups
• Configure dashboard section: Updates a section's title, description, or collapsed state
• Remove dashboard section: Removes a section divider from a dashboard
• Move charts: Rearranges chart positions on the dashboard grid

Example queries

• "Show me the details for chart #456 on my dashboard"
  
• "What chart types and settings are available?"
  
• "Add a line chart showing error rates per minute to dashboard #1234"
  
• "Change chart #456 to a bar chart"
  
• "Remove chart #789 from the dashboard"
  
• "Add a 'Performance Metrics' section to dashboard #1234"
  
• "Move chart #456 to the top-left position"

Alerts

• List chart alerts: Lists chart alerts with their ID, name, chart, and status
• Get chart alert details: Shows configuration of a specific alert including its configuration, SQL queries, and current incident info
• Get chart alert instructions: Provides instructions for creating and configuring chart alerts, including alert types and operators
• Create chart alert: Creates a new alert on an existing chart with support for threshold, relative, and anomaly detection alert types
• Configure chart alert: Updates an existing chart alert's configuration
• Remove chart alert: Permanently removes a chart alert
• Pause or resume chart alert: Pauses or unpauses a chart alert

Example queries

• "List all chart alerts on my Nginx dashboard"
• "Create a threshold alert on my CPU usage chart that triggers when it exceeds 90%"
• "Change the confirmation period on alert #1234 to 5 minutes"
• "Delete the traffic drop alert, we no longer need it"

Logs & spans

Query and explore logs and distributed traces.

Query building

• Get query instructions: Provides instructions for building logs and spans queries to run directly via the query tools
• Get explore logs query instructions: Provides instructions for writing queries for the Explore logs page and live-tail charts

Example queries

• "Build a query to find all ERROR level logs from my API service"
• "Show me how to query logs with response times above 1 second"
• "Find all HTTP 500 errors in the last 24 hours"

Metrics

Build dashboards and analyze performance trends.

Metrics catalog

• Get metrics schema: Shows available metrics with data points and series count
• Get metric details: Explains how to query and use specific metrics with examples
• Get metric query instructions: Provides instructions for building metrics queries to run directly via the query tools

Example queries

• "Show me all available metrics for my production source"
• "Get details for the response_time metric including example queries"
• "Build a dashboard query for average CPU usage over time"
• "What aggregation functions are available for memory metrics?"

Metric expressions

Extract metrics and labels from your logs.

• List metric expressions: Lists the extract-metrics-from-logs rules on a source
• Create metric expression: Creates a new metric or label extracted from log fields
• Update metric expression: Updates an existing metric expression's name, SQL expression, type, or aggregations
• Remove metric expression: Deletes a metric expression from a source

Example queries

• "Extract the HTTP status code from my logs as a metric"
• "List all metric expressions on my production source"
• "Change the request_duration metric to also track the average"

Infrastructure

Manage data regions, clusters, and secure connections.

Data regions and clusters

• List data regions: Shows available regions for storing data
• List clusters: Lists storage clusters for direct data access
• List teams: Shows teams with telemetry platform access

Cloud connections

• Create cloud connection: Creates temporary credentials for direct ClickHouse access

Example queries

• "List all available data regions for creating a new source"
• "Show me storage clusters in the Europe region"
• "Create a cloud connection for direct access to my logs data"
• "What teams have access to the telemetry platform?"

Error tools

Your AI assistant can manage error tracking applications, analyze exceptions, and query error data through natural language. Ask questions like:

• "Show me all error tracking applications"
• "Create a new Python error tracking application"
• "What errors occurred in production this week?"
• "Show me all releases for my application"
• "Build a query to find the most frequent exceptions"

Applications

Manage error tracking applications and their configuration.

Application management

• List applications: Shows all error tracking applications with status and configuration
• Get application details: Provides detailed configuration, ingestion settings, and available data tables
• Create application: Creates new error tracking applications with platform-specific integration guides

Example queries

• "List all my error tracking applications"
• "Create a new JavaScript application for error tracking in the US East region"
• "Get details for application #1234 including the DSN and collection names"
• "Show me all applications that are currently paused"

Releases

Track application releases and their error patterns.

• List releases: Shows all releases for an application with first and last seen timestamps

Example queries

• "Show me all releases for my production application"
• "List releases deployed in the last week"
• "What environments is release v2.1.0 running in?"

Error details and management

View detailed error information and manage error states for triage and resolution tracking.

• List errors: Lists error patterns for an application with occurrence counts, affected users, and current state — supports filtering by state, release, environment, or time range
• Get error details: Shows comprehensive error information including type, message, call site, first occurrence, and current state (unhandled, unresolved, ignored, resolved, or reoccurred)
• Update error state: Changes error state to mark errors as resolved, ignored, or unresolved with optional notification settings

Example queries

• "List all unresolved errors from the last 3 days in production"
• "Get details for error pattern abc123 in application #1234"
• "Show me the current state and call site information for this error"
• "Mark error pattern xyz789 as resolved"
• "Ignore error pattern abc123 for the next 100 occurrences"
• "Mark this error as unresolved and notify on every exception"

Replays

Query session replay data linked to errors and user sessions.

• Get replays query instructions: Provides instructions for querying session replay data, including data structure, fields, and query patterns for finding replays linked to errors or specific users

Example queries

• "Show me how to query session replays for my application"
• "Find replays linked to error pattern abc123"
• "Get instructions for finding replays from a specific user"

Error queries

Build and execute ClickHouse queries to analyze error patterns and individual exceptions.

Query building

• Get errors query instructions: Provides comprehensive documentation for querying error data including the two-layer architecture (errors and exceptions), available columns, query patterns, and best practices

Example queries

• "Show me how to query error patterns for my application"
• "Get instructions for building queries to analyze individual exception occurrences"
• "What's the difference between the metrics and exceptions sources?"
• "How do I query errors by release version?"

Next steps 🚀

• Get started with Uptime monitoring to set up monitors and alerting that your AI assistant can manage.
• Explore Telemetry to build comprehensive observability with your AI assistant analyzing your data.

Have any questions?

Please feel free to message us at hello@betterstack.com. We'll get back to you as soon as we can, typically within a few hours. 🙏 Thank you!