Using Cursor? Click here to add the Better Stack MCP server
Explore documentation
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"
}
}
}
}
Using Claude? Check out Connect to Local MCP Servers for setup instructions.
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 & 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 schedulesList on-call calendars
: Provides information about on-call calendars and rotationsList on-call events
: Lists upcoming shifts and schedule changesGet on-call event details
: Fetches details for specific on-call eventsGet 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 incidentsList escalation policies
: Lists configured escalation rules and stepsGet escalation policy details
: Provides detailed policy informationList severities
: Shows incident severity levels and configurationsGet 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 metadataList incidents
: Finds incidents by date, status, monitor, or other criteriaGet incident details
: Shows full incident information including error messages and screenshotsGet incident timeline
: Displays complete incident historyGet incident comments
: Retrieves incident commentsCreate incident comment
: Adds team collaboration commentsAcknowledge incident
: Takes ownership of incidents to stop escalationsEscalate incident
: Routes incidents to users, teams, or policiesResolve 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 optionsGet monitor details
: Provides monitor configuration, status, and settingsGet monitor availability
: Calculates SLA summaries and uptime percentagesGet 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 statusGet heartbeat details
: Provides heartbeat configuration and recent activityGet 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 pagesGet status page details
: Provides status page configuration and current statusGet status page resources
: Lists monitors and heartbeats displayed on each pageCreate status page report
: Creates incident reports or maintenance announcementsCreate status page report update
: Adds updates to ongoing reportsList status page reports
: Shows status reports for a specific pageList status page report updates
: Lists updates for a specific reportGet 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 configurationGet source details
: Provides detailed source configuration and settingsCreate source
: Creates new log sources with integration guidesGet 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 dataGet query instructions
: Provides context to help create better ClickHouse queriesquery
: 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 countGet metric details
: Explains how to query and use specific metrics with examplesBuild metric query
: Generates ClickHouse queries for dashboard visualizationsGet 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 dataList clusters
: Lists storage clusters for direct data accessList 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?"
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!