# 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](https://betterstack.com/community/guides/ai/mcp-explained/) 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](https://betterstack.com/docs/uptime/api/getting-started-with-uptime-api/) 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: ```json [label OAuth configuration (recommended)] { "mcpServers": { "betterstack": { "type": "http", "url": "https://mcp.betterstack.com" } } } ``` If you're using [Claude Code](https://docs.anthropic.com/en/docs/claude-code), you can add the server directly from the CLI: ```bash [label Install with Claude Code] claude mcp add betterstack --transport http https://mcp.betterstack.com ``` [info] **Using Cursor?** Click here to add the [Better Stack MCP server](https://cursor.com/en/install-mcp?name=better-stack&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vbWNwLmJldHRlcnN0YWNrLmNvbSJ9) [/info] **API token** For clients that support HTTP servers but not OAuth, pass your API token via the `Authorization` header: ```json [label API token configuration] { "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: ```json [label Proxy configuration (mcp-remote)] { "mcpServers": { "betterstack": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.betterstack.com", "--header", "Authorization: Bearer ${BETTERSTACK_API_TOKEN}" ], "env": { "BETTERSTACK_API_TOKEN": "$TOKEN" } } } } ``` [info] **Using Claude?** Check out [Connect to Local MCP Servers](https://modelcontextprotocol.io/quickstart/user) for setup instructions. [/info] ### 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** ```json [label Allowlist 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** ```json [label 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" #### Alerts - `List chart alerts`: List 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 - `Create chart alert`: Creates a new alert on an existing chart with support for threshold, relative, and anomaly detection alert types - `Edit chart alert`: Updates an existing chart alert's configuration - `Delete chart alert`: Permanently removes a chart alert - `Toggle chart alert pause`: 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 - `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](https://betterstack.com/docs/uptime/start/) to set up monitors and alerting that your AI assistant can manage. - [Explore Telemetry](https://betterstack.com/docs/logs/start/) 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!