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: Generate your API token

You'll need a Better Stack API token to authenticate the MCP server. Follow our API authentication guide to create one.

Step 2: Install the MCP server

The Better Stack MCP server runs as a remote HTTP server. Add this configuration to your MCP client:

For clients supporting HTTP servers:

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

For clients without HTTP server support:

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"

Query your logs, traces, errors & metrics

You can execute ClickHouse queries directly against your Better Stack data. For optimal performance, include your cloud connection details via headers:

{
  "mcpServers": {
    "better-stack": {
      "type": "http",
      "url": "http://mcp.betterstack.com/",
      "headers": {
        "Authorization": "Bearer $TOKEN",
        "X-Connection-User": "user",
        "X-Connection-Password": "password",
        "X-Connection-Host": "host"
      }
    }
  }
}

Or if your client doesn't support remote MCP servers

{
  "mcpServers": {
    "better-stack": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.betterstack.com/",
        "--header",
        "Authorization: Bearer ${BETTER_STACK_PRODUCTION_AUTH_TOKEN}",
        "--header",
        "X-Connection-User: ${BETTER_STACK_CONNECTION_USER}",
        "--header",
        "X-Connection-Password: ${BETTER_STACK_CONNECTION_PASSWORD}",
        "--header",
        "X-Connection-Host: ${BETTER_STACK_CONNECTION_HOST}"
      ],
      "env": {
        "BETTER_STACK_PRODUCTION_AUTH_TOKEN": "$TOKEN",
        "BETTER_STACK_CONNECTION_USER": "user",
        "BETTER_STACK_CONNECTION_PASSWORD": "password",
        "BETTER_STACK_CONNECTION_HOST": "host"
      }
    }
  }
}

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"

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"

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
• query: Executes ClickHouse queries directly against telemetry data

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"
• "Execute a query to get the top 10 error messages from today"

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

Errors

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"

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!