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: Authenticate

There are two ways to connect your AI assistant to the Better Stack MCP server:

• OAuth (recommended): MCP clients that support OAuth will automatically prompt you to sign in through the browser. No token configuration needed.
• API token: For clients without OAuth support, follow our API authentication guide to create an API token.

Step 2: 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:

{
  "mcpServers": {
    "betterstack": {
      "type": "http",
      "url": "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 3: 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": "uptime_list_monitors,uptime_get_monitor_details,uptime_list_incidents"
      }
    }
  }
}

Exclude specific tools

{
  "mcpServers": {
    "betterstack": {
      "type": "http",
      "url": "https://mcp.betterstack.com",
      "headers": {
        "Authorization": "Bearer $TOKEN",
        "X-MCP-Tools-Except": "telemetry_remove_dashboard,telemetry_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.

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 incident escalation options: 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, or policies
• Resolve incident: Marks incidents as fixed

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"

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
• 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"

Heartbeats

• List heartbeats: Shows all heartbeat monitors and their status
• Get heartbeat details: Provides heartbeat configuration and recent activity
• 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?"

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
• Get status page resources: Lists monitors and heartbeats displayed on each 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"

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 line chart: Executes a ClickHouse SQL query and renders the result as a line 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
• Rename dashboard: Renames an existing dashboard
• 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
• Add chart to dashboard: Adds a new chart with a SQL query to a dashboard
• Edit chart: Updates a chart's name, type, or query
• Remove chart: Permanently removes a chart from its dashboard
• Add dashboard section: Adds a section divider to organize charts into groups
• 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"

Logs & spans

Query and explore logs and distributed traces.

Query building

• Build explore query: Generates ClickHouse queries from natural language for exploring data
• Get query instructions: Provides context to help create better ClickHouse queries

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 and cardinality: Shows available metrics with data points and series count
• Get metric details: Explains how to query and use specific metrics with examples
• Build metric query: Generates ClickHouse queries for dashboard visualizations
• Get metric query instructions: Provides context for building metrics queries

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?"

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.

• 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

• "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!