byok-observability-mcp
Bring Your Own Keys — credentials stay in env vars on your machine. No clone, no build, runs via npx.
Partial setup — configure only the backends you use. Tools for unconfigured backends are never exposed.
How it works
Related MCP server: kubernetes-mcp
⚡ Quick Start
Option A — Interactive wizard (recommended)
Run once, answer a few questions, get a ready-made .mcp.json:
npx byok-observability-mcp --initThe wizard will:
Let you pick which backends to configure
Ask for credentials per service
Test connectivity with your real endpoints before writing anything
Write
.mcp.jsonto your project root or~/.claude/— your choice
Then just start Claude Code:
claudeThat's it. No clone, no build, no env file. Works in under 60 seconds.
Option B — Manual .mcp.json
Create .mcp.json in your project root. Include only the backends you need.
{
"mcpServers": {
"observability-mcp": {
"command": "npx",
"args": ["-y", "byok-observability-mcp"],
"env": {
"GRAFANA_URL": "https://grafana.mycompany.internal",
"GRAFANA_TOKEN": "glsa_...",
"PROMETHEUS_URL": "https://prometheus.mycompany.internal",
"KAFKA_UI_URL": "https://kafka-ui.mycompany.internal",
"DD_API_KEY": "your-datadog-api-key",
"DD_APP_KEY": "your-datadog-app-key"
}
}
}
}Credentials in git? Use the
${VAR}approach instead — see Configuration → Method B.
Start Claude Code:
claudeClaude Code reads .mcp.json automatically. No claude mcp add, no build step.
Verify by asking Claude:
What observability tools do you have available?🧩 Supported clients
Client | Configuration |
Claude Code |
|
OpenAI Codex CLI |
|
Both clients read .mcp.json automatically. The Quick Start above works for either.
# Same .mcp.json as above works out of the box
codexOr add via CLI:
codex mcp add --transport stdio observability-mcp -- npx -y byok-observability-mcp🔧 Available tools
Always available. Checks connectivity across all configured backends.
Tool | Description |
| Unified Health Check. Runs a parallel check on all backends and returns a status table. |
Enabled when
GRAFANA_URL+GRAFANA_TOKENare set.
Tool | Description |
| Check connectivity, version, and database status |
| List all datasources (name, type, UID) |
| Run a PromQL expression via a Grafana datasource |
| Search and list dashboards by name or tag |
| Get panels and metadata for a dashboard by UID |
| List active alerts from Alertmanager (firing/pending) |
| List all configured alert rules across all folders |
Enabled when
PROMETHEUS_URLis set.
Tool | Description |
| Check connectivity |
| Instant PromQL query — current value of a metric |
| Range PromQL query — metric values over time |
| List all available metric names |
| Get help text and type for a specific metric |
Enabled when
KAFKA_UI_URLis set.
Tool | Description |
| List configured Kafka clusters and their status |
| List topics in a cluster |
| Get partition count, replication factor, and config |
| List consumer groups and their state |
| Get per-partition lag for a consumer group |
| Broker count and disk usage per broker |
Enabled when both
DD_API_KEYandDD_APP_KEYare set. Proxies the official Datadog MCP server.
Default toolsets: core, apm, alerting. Set DD_TOOLSETS=all to load everything.
Toolset | Covers |
| Metrics, dashboards, monitors, infrastructure |
| APM services, traces, service map |
| Monitors, downtimes, alerts |
| Log search and analytics |
| Incident management |
| SQL-style metric queries |
| Cloud security posture |
| Synthetic test results |
| Network performance monitoring |
| Database monitoring |
| CI/CD pipelines |
| LLM observability |
| Case management |
| Feature flag tracking |
🔑 Getting credentials
Open Grafana → Administration → Users and access → Service accounts
Click Add service account → set Role to
Viewer→ CreateOn the service account page → Add service account token → Generate token
Copy the token (starts with
glsa_) — you won't see it again
GRAFANA_URL=https://grafana.mycompany.internal
GRAFANA_TOKEN=glsa_xxxxxxxxxxxxxxxxIf your Grafana uses a self-signed certificate:
GRAFANA_VERIFY_SSL=falseIf Prometheus has no authentication:
PROMETHEUS_URL=https://prometheus.mycompany.internalIf Prometheus uses basic auth:
PROMETHEUS_URL=https://prometheus.mycompany.internal
PROMETHEUS_USERNAME=your-username
PROMETHEUS_PASSWORD=your-passwordIf Kafka UI has no authentication:
KAFKA_UI_URL=https://kafka-ui.mycompany.internalIf Kafka UI requires a login:
KAFKA_UI_URL=https://kafka-ui.mycompany.internal
KAFKA_UI_USERNAME=admin
KAFKA_UI_PASSWORD=your-passwordAPI key: Datadog → Organization Settings → API Keys → New Key
Application key: Datadog → Organization Settings → Application Keys → New Key
DD_SITE — match your Datadog login URL:
Login URL | DD_SITE |
|
|
|
|
|
|
|
|
|
|
DD_API_KEY=your-api-key
DD_APP_KEY=your-application-key
DD_SITE=datadoghq.com
DD_TOOLSETS=core,apm,alerting⚙️ Configuration
Method A — Values directly in .mcp.json (simplest)
Put credentials directly in .mcp.json. Works everywhere, no extra steps.
Add .mcp.json to your .gitignore if the repo is shared.
Use ${VAR} placeholders in .mcp.json and put real values in .env.
.mcp.json (safe to commit — contains no secrets):
{
"mcpServers": {
"observability-mcp": {
"command": "npx",
"args": ["-y", "byok-observability-mcp"],
"env": {
"GRAFANA_URL": "${GRAFANA_URL}",
"GRAFANA_TOKEN": "${GRAFANA_TOKEN}",
"PROMETHEUS_URL": "${PROMETHEUS_URL}",
"KAFKA_UI_URL": "${KAFKA_UI_URL}",
"DD_API_KEY": "${DD_API_KEY}",
"DD_APP_KEY": "${DD_APP_KEY}"
}
}
}
}.env (add to .gitignore):
GRAFANA_URL=https://grafana.mycompany.internal
GRAFANA_TOKEN=glsa_...Start Claude with the env loaded:
set -a && source .env && set +a && claudeA ready-made helper script is included:
./scripts/run-claude-with-env.shA template .mcp.json with all variables is available as .mcp.json.example.
Add to ~/.claude.json:
{
"mcpServers": {
"observability-mcp": {
"command": "npx",
"args": ["-y", "byok-observability-mcp"],
"env": {
"GRAFANA_URL": "https://grafana.mycompany.internal",
"GRAFANA_TOKEN": "glsa_..."
}
}
}
}📋 Environment variables
Variable | Backend | Required | Description |
| Grafana | ✅ | Base URL of your Grafana instance |
| Grafana | ✅ | Service account token (Viewer role) |
| Grafana | Set to | |
| Prometheus | ✅ | Base URL of your Prometheus instance |
| Prometheus | Basic auth username | |
| Prometheus | Basic auth password | |
| Kafka UI | ✅ | Base URL of your Kafka UI instance |
| Kafka UI | Login username | |
| Kafka UI | Login password | |
| Datadog | ✅ | Datadog API key |
| Datadog | ✅ | Datadog Application key |
| Datadog | Datadog site (default: | |
| Datadog | Tool groups to load (default: | |
| Reports | ✅* | Slack Incoming Webhook URL for scheduled reports |
| Reports | Comma-separated backends to include in reports (default: all configured) |
📊 Scheduled Reports
Send an automated observability digest to Slack on a schedule — no Claude or Codex instance needs to be running.
How it works
cron / launchd
│ fires every N minutes
▼
npx byok-observability-mcp --report
│
│ reads env vars, connects directly to backends
▼
Grafana · Prometheus · Kafka UI
│
│ categorizes findings → P0 / P1 / P2 / P3
▼
Slack Incoming Webhook → #your-channelThe command collects data, categorizes every finding by severity, formats a Slack message, sends it, and exits. It is completely stateless.
Severity levels
Level | Meaning | Examples |
🔴 P0 — KRİTİK | Service down or unreachable | Grafana alert firing (critical), Kafka cluster offline, backend unreachable |
🟠 P1 — YÜKSEK | Degraded, action needed soon | Grafana alert firing (non-critical), Kafka consumer lag > 10 000 |
🟡 P2 — ORTA | Warning, monitor closely | Grafana alert pending, Kafka consumer lag > 1 000 |
🟢 P3 — BİLGİ | Informational, all normal | Healthy backends, silenced alerts |
Setup
Step 1 — Get a Slack Incoming Webhook URL
Go to api.slack.com/apps → Create New App → From scratch
Incoming Webhooks → toggle on → Add New Webhook to Workspace
Pick a channel → Allow → copy the Webhook URL
Step 2 — Set environment variables
export SLACK_WEBHOOK_URL=https://hooks.slack.com/services/XXX/YYY/ZZZ
# Optional: restrict which backends are included (default: all configured)
export REPORT_BACKENDS=grafana,prometheus,kafkaStep 3 — Run a one-off report to verify
npx byok-observability-mcp --reportYou should see a message in your Slack channel within seconds.
Step 4 — Schedule with cron
Open your crontab:
crontab -eAdd a line. Examples:
# Every hour at minute 0
0 * * * * SLACK_WEBHOOK_URL=https://hooks.slack.com/... GRAFANA_URL=... GRAFANA_TOKEN=... npx byok-observability-mcp --report >> /tmp/obs-report.log 2>&1
# Every 30 minutes
*/30 * * * * SLACK_WEBHOOK_URL=https://hooks.slack.com/... npx byok-observability-mcp --report >> /tmp/obs-report.log 2>&1Put all env vars in a.env file and source it inside the cron command to keep the crontab clean:
0 * * * * bash -c 'source /path/to/.env && npx byok-observability-mcp --report' >> /tmp/obs-report.log 2>&1Alternative: macOS launchd (runs on login, survives reboots)
Create ~/Library/LaunchAgents/com.observability-mcp.report.plist:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.observability-mcp.report</string>
<key>ProgramArguments</key>
<array>
<string>/usr/local/bin/npx</string>
<string>byok-observability-mcp</string>
<string>--report</string>
</array>
<key>EnvironmentVariables</key>
<dict>
<key>SLACK_WEBHOOK_URL</key>
<string>https://hooks.slack.com/services/XXX/YYY/ZZZ</string>
<key>GRAFANA_URL</key>
<string>https://grafana.mycompany.internal</string>
<key>GRAFANA_TOKEN</key>
<string>glsa_...</string>
</dict>
<key>StartInterval</key>
<integer>3600</integer>
<key>StandardOutPath</key>
<string>/tmp/obs-report.log</string>
<key>StandardErrorPath</key>
<string>/tmp/obs-report.log</string>
</dict>
</plist>Load it:
launchctl load ~/Library/LaunchAgents/com.observability-mcp.report.plistTo stop: launchctl unload ~/Library/LaunchAgents/com.observability-mcp.report.plist
💬 Example prompts
Single-backend queries
Backend | Try asking Claude... |
Grafana | "List all datasources and tell me which ones are Prometheus type." |
Grafana | "Search for dashboards related to 'kubernetes' — list names and UIDs." |
Grafana | "Query |
Prometheus | "What is the current value of the |
Prometheus | "Show CPU usage ( |
Prometheus | "List all available metrics that start with |
Kafka UI | "List all Kafka clusters. Are there any with offline brokers?" |
Kafka UI | "Describe the topic 'orders' in cluster 'production' — partitions and replication factor?" |
Kafka UI | "Check consumer lag for group 'order-processor'. Which partitions have the highest lag?" |
Datadog | "List all Datadog monitors currently in Alert state." |
Datadog | "Show APM service performance for the past hour. Which services have the highest error rate?" |
Datadog | "Query |
🛠️ Incident Response (v0.2.0+)
Goal | Try asking Claude... |
Health | "Run a health check on all systems." |
Alerts | "Are there any firing alerts in Grafana right now?" |
Triage | "Show me the alert rules for the 'Production' folder." |
Cross-backend queries
Check the health of all configured observability backends and give me a summary.I'm seeing high error rates. Check Prometheus for http_requests_total with status=500,
then look for related Datadog monitors that might be alerting.🔒 Security
All tools areread-only. No write operations are performed on any backend.
Credentials are read from environment variables andnever logged or sent to Anthropic. Tokens are redacted in all error messages.
TLS certificate verification is enabled by default
The MCP process runs locally — your infrastructure URLs only reach Claude's context window if you type them into the chat
Least-privilege recommendations:
Backend | Recommended role |
Grafana | Service account with Viewer role |
Prometheus | Network-level read-only access |
Kafka UI | Read-only UI user |
Datadog | API key + Application key with read scopes |
🛠 Development
git clone https://github.com/alimuratkuslu/byok-observability-mcp
cd byok-observability-mcp
npm install
npm run dev # run with tsx (no build step)
npm run build # compile to dist/
npm run typecheck # TypeScript check without emittingTested versions
Backend | Tested version |
Grafana | v9.x, v10.x, v11.x |
Prometheus | v2.x |
Kafka UI |
|
License
MIT
Available Tools
23 toolsgrafana_get_alert_rulesA
List all configured Grafana alert rules from the provisioning API. Returns rule UID, title, condition, labels, annotations, folder, and rule group. Use this to see what alert rules are defined.
Inputs: no named parameters.
grafana_get_dashboardA
Get full details of a Grafana dashboard including all panels, by its UID. Use grafana_list_dashboards to find the UID.
Inputs: uid (required).
grafana_healthA
Check Grafana connectivity and retrieve version and database status. Use this to verify the Grafana integration is working.
Inputs: no named parameters.
grafana_list_alertsA
List active (or filtered) alerts from Grafana Alertmanager. Supports filtering by state and label selectors. Returns alert name, state, severity, labels, annotations, and start time. Use this to answer 'are there any firing alerts right now?'
Inputs: state, labels.
grafana_list_dashboardsA
List dashboards in Grafana with an optional search query. Returns UID, title, folder, and tags.
Inputs: query.
grafana_list_datasourcesA
List all datasources configured in Grafana (name, type, UID). Use this to find the UID needed for grafana_query_metrics.
Inputs: no named parameters.
grafana_query_metricsA
Execute a PromQL expression via a Grafana Prometheus datasource and return the results. Use grafana_list_datasources first to find the datasource UID.
Inputs: datasource_uid (required), expr (required), from, to, +1 more.
kafka_broker_healthC
Get broker health for a Kafka cluster — broker IDs, hosts, ports, and disk usage.
Inputs: cluster_name (required).
kafka_consumer_group_lagA
Get consumer lag for a specific consumer group — per-partition offset, end offset, and lag. Highlights partitions with non-zero lag.
Inputs: cluster_name (required), group_id (required).
kafka_describe_topicC
Get detailed information about a specific Kafka topic including partition layout, replication, and segment info.
Inputs: cluster_name (required), topic_name (required).
kafka_list_clustersA
List all Kafka clusters configured in Kafka UI. Returns name, status, broker count, topic count, and partition info.
Inputs: no named parameters.
kafka_list_consumer_groupsC
List consumer groups in a Kafka cluster with their state and member count.
Inputs: cluster_name (required), page, per_page.
kafka_list_topicsA
List topics in a Kafka cluster with partition count, replication factor, and under-replicated partition count.
Inputs: cluster_name (required), page, per_page.
obs_health_checkA
Run a health check across all configured observability backends (Grafana, Prometheus, Kafka UI, Datadog) in parallel and return a status summary table. Use this to answer 'are all systems up?'
Inputs: no named parameters.
obs_investigate_incidentA
Meta-tool that performs parallel root cause analysis (RCA) queries across all enabled backends. Automatically checks Grafana for firing alerts, Prometheus for offline endpoints (up==0), and Kafka clusters for offline brokers.
Inputs: no named parameters.
opsgenie_ack_alertC
Acknowledge an open OpsGenie alert to prevent escalations.
Inputs: alert_id (required).
opsgenie_list_alertsC
List currently open OpsGenie alerts. Returns ID, tinyId, message, priority, and acknowledged status.
Inputs: limit.
opsgenie_who_is_on_callB
List current on-call participants for all schedules. Helps you find who to page.
Inputs: no named parameters.
prometheus_healthB
Check Prometheus connectivity. Returns healthy/unhealthy status.
Inputs: no named parameters.
prometheus_list_metricsB
List all available metric names in Prometheus. Useful for discovery when you don't know the exact metric name.
Inputs: no named parameters.
prometheus_metric_metadataA
Get help text, type, and unit for a specific Prometheus metric. Omit metric_name to list all metadata.
Inputs: metric_name.
prometheus_queryA
Execute an instant PromQL query and return the current value(s). Best for checking current state of a metric (e.g. CPU usage right now).
Inputs: query (required), time.
prometheus_query_rangeA
Execute a PromQL range query and return a time series. Use this to see how a metric changed over time.
Inputs: query (required), start, end, step.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Most tools are clearly distinct by backend (Grafana, Kafka, OpsGenie, Prometheus) and action, with minimal overlap. However, some potential confusion exists between grafana_list_alerts (active alerts) and grafana_get_alert_rules (configured rules), and between prometheus_query (instant) and prometheus_query_range (range), though descriptions help clarify.
Tool names follow a highly consistent backend_action_resource pattern (e.g., grafana_list_dashboards, kafka_describe_topic, prometheus_query_range). All use snake_case, and verbs like 'list', 'get', 'query' are applied predictably across backends, making the set easy to navigate.
With 23 tools, the count is on the high side for a single server, potentially overwhelming. However, given the broad observability domain covering multiple backends (Grafana, Kafka, OpsGenie, Prometheus), it's borderline but justifiable as each tool serves a specific purpose.
The toolset provides comprehensive read/query capabilities across all backends, with good coverage for monitoring, alerting, and incident investigation. Minor gaps include lack of write/update tools (e.g., creating dashboards or alerts) and limited OpsGenie actions beyond listing and acknowledging, but core workflows are well-supported.
Maintenance
Related MCP Connectors
An MCP server giving access to Grafana dashboards, data and more.
The Buildkite MCP server exposes Buildkite product data (pipelines, builds, jobs, and test data) to AI tools, editors, and agents through the Model Context Protocol. It provides capabilities including pipeline creation and management, build monitoring with specialized tools like 'wait_for_build', efficient log querying using Apache Parquet conversion and caching, and OAuth-based authentication for both read-write and read-only access to Buildkite's REST API.
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
Related MCP Servers
AlicenseBqualityDmaintenanceA Model Context Protocol server that lets AI assistants interact with the Sentry API to retrieve and analyze error data, manage projects, and monitor application performance.1112ISC- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server that provides safe, read-only access to Kubernetes resources for debugging and inspection. Built with security in mind, it offers comprehensive cluster visibility without modification capabilities.45MIT
- AlicenseBqualityDmaintenanceEnables interaction with Datadog's monitoring and observability platform through the MCP protocol. Supports incident management, monitor status checks, log searches, metrics queries, APM traces, dashboard access, RUM analytics, host management, and downtime scheduling.13Apache 2.0
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables querying logs and metrics from Graylog, Prometheus, and InfluxDB 2.x. It provides tools for executing Lucene log searches, PromQL queries, and Flux queries directly within MCP-compatible clients.MIT