Lucid Observability Agent
Integrates with PostgreSQL to monitor OpenMeter billing pipeline health, including outbox queue depth, dead letter retry, and usage anomaly detection.
Provides tools for error tracking and monitoring via Sentry, including listing and resolving issues, searching by trace ID, and generating alert rules based on error patterns.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Lucid Observability Agent check openmeter billing pipeline health"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Lucid Observability Agent
MCP server and OpenClaw plugin for monitoring, diagnosing, and auto-correcting observability issues across platform services. Connects to Sentry for error tracking, PostgreSQL for OpenMeter billing pipeline health, and ships with AI-powered diagnosis, incident runbooks, and cross-service correlation.
Unlike the official Sentry MCP server (which is a pure API wrapper), this agent adds:
Root cause analysis --- pattern matching against error titles, stack traces, and platform-specific knowledge
Cross-service correlation --- traces errors across multiple services via
trace_id/run_idBilling pipeline monitoring --- outbox health, dead letter recovery, usage anomaly detection
Incident runbooks --- 10 error categories with 5-phase playbooks (triage -> diagnose -> mitigate -> resolve -> postmortem)
Alert rule generation --- suggests Sentry alert rules based on actual error patterns
Production readiness auditing --- validates env vars, conventions, and configuration
v3.0.0 --- Dual entry point architecture: works as both an MCP server (Claude Code / Claude Desktop) and an OpenClaw plugin with slash commands and heartbeat support.
Quick Start
As MCP Server (Claude Code)
Install from npm and run directly:
npx lucid-obs-agentOr add to your MCP config (~/.claude.json or Claude Desktop settings):
{
"mcpServers": {
"observability": {
"command": "npx",
"args": ["lucid-obs-agent"],
"env": {
"SENTRY_AUTH_TOKEN": "sntrys_...",
"SENTRY_ORG": "your-org",
"DATABASE_URL": "postgresql://..."
}
}
}
}Or run from source:
{
"mcpServers": {
"observability": {
"command": "npx",
"args": ["tsx", "/path/to/lucid-observability-agent/src/bin.ts"],
"env": {
"SENTRY_AUTH_TOKEN": "sntrys_...",
"DATABASE_URL": "postgresql://..."
}
}
}
}As OpenClaw Plugin
Install the package:
npm install lucid-observability-agentAdd to your
openclaw.json:
{
"plugins": [
{
"id": "lucid-observability",
"package": "lucid-observability-agent",
"config": {
"sentryAuthToken": "sntrys_...",
"sentryOrg": "your-org",
"databaseUrl": "postgresql://..."
}
}
]
}The plugin registers all 16 tools, 3 resources, 3 prompts, and 2 slash commands automatically.
Related MCP server: MCP Prometheus
Environment Variables
Variable | Required | Description |
| Yes | Sentry internal integration token (scopes: |
| No | Sentry org slug (overrides config default) |
| For metering tools | PostgreSQL connection string for OpenMeter outbox |
| No | Path to custom config JSON (see Configuration) |
Tools (16)
Sentry (6)
Tool | Description |
| List issues by project with Sentry search syntax |
| Full detail: stack trace, tags, contexts, cross-links |
| Event history with temporal pattern detection |
| Resolve, ignore, or unresolve issues |
| Find errors by OTel trace ID |
| Error rate trends over time |
Diagnosis (2)
Tool | Description |
| Root cause analysis with configurable patterns |
| Cross-service error correlation via trace_id/run_id |
OpenMeter (4)
Tool | Description |
| Queue depth, dead letters, stuck leases |
| Per-org token/tool usage breakdown |
| Retry failed dead-letter events |
| Spike/drop detection vs rolling baseline |
Configuration (2)
Tool | Description |
| Audit env vars for production readiness |
| Verify service uses standard conventions |
Auto-Fix (2)
Tool | Description |
| Generate Sentry alert configs from patterns |
| Incident runbook for 10 error categories |
Resources (3)
URI | Description |
| Span names, attribute keys, rules |
| Service topology and dependencies |
| Sampling strategy reference |
Prompts (3)
Prompt | Description |
| 6-step issue triage workflow |
| Full production audit scorecard |
| 4-phase incident response protocol |
These prompts are also documented with full workflows in SKILL.md.
Commands (OpenClaw)
When running as an OpenClaw plugin, two slash commands are available:
Command | Description |
| Show observability agent status --- config, services, connections |
| Run observability health checks --- config audit + outbox health |
OpenClaw Heartbeat
OpenClaw supports autonomous monitoring via a HEARTBEAT.md file. The agent runs the checks on a schedule and reports findings without manual prompting.
Add a HEARTBEAT.md to your project root (or reference the checklist in SKILL.md):
## Observability Checks
- Run `openmeter_outbox_health` — alert if dead letters > 0 or stuck leases
- Run `sentry_list_issues` sorted by freq — flag issues with count > 100
- Run `check_config_health` — warn if any critical checks failing
- If issues found, run `diagnose_issue` and suggest resolutionThe heartbeat runs these checks periodically and surfaces warnings or critical findings through OpenClaw's notification system.
Configuration
The agent ships with Lucid platform defaults (config/lucid.json). Override by setting AGENT_CONFIG_PATH:
AGENT_CONFIG_PATH=./my-config.json npx lucid-obs-agentWhen using the OpenClaw plugin, pass the config path via plugin config:
{
"configPath": "./config/my-config.json"
}See config/example.json for a minimal config template.
Development
git clone https://github.com/daishizenSensei/lucid-observability-agent
cd lucid-observability-agent
npm install
npm run typecheck # Verify types
npm run dev # Start with tsx (hot reload)
npm run build # Build with tsup to dist/
npm run start # Run built outputProject Structure
src/
bin.ts # CLI entry point (MCP stdio server)
index.ts # Package re-export (core + mcp + openclaw)
mcp.ts # MCP server setup (tools, resources, prompts)
openclaw.ts # OpenClaw plugin entry (tools, commands, skills)
core/
tools/ # 16 tool definitions (ToolParamDef format)
resources/ # 3 resource data providers
commands/ # /obs-status, /obs-check handlers
config/ # Config loading and defaults
helpers/ # Sentry API, DB client, shared utils
types/ # TypeScript type definitionsLicense
MIT
Available Tools
16 toolscheck_config_healthB
Audit observability configuration for production readiness. Checks Sentry, OTel, metering, PII, and environment settings.
Inputs: environment.
check_conventionsC
Verify a service uses standard observability conventions: canonical names, required spans, attribute keys.
Inputs: service (required).
cross_correlateA
Correlate errors across services using trace_id or run_id. Finds related Sentry issues across all projects to build a cross-service error timeline.
Inputs: runId, traceId.
diagnose_issueB
Deep root-cause analysis of a Sentry issue. Examines stack trace, error patterns, frequency, and platform-specific knowledge to produce actionable diagnosis.
Inputs: issueId (required).
generate_runbookB
Generate an incident runbook for a specific error category with triage, diagnosis, mitigation, resolution, and postmortem steps.
Inputs: category (required), service.
openmeter_dead_letter_retryA
Retry dead-letter events that have failed max attempts. Resets attempt count so the outbox worker picks them up again.
Inputs: orgId, maxEvents.
openmeter_outbox_healthB
Check OpenMeter outbox queue health: pending events, dead letters, stuck leases, throughput.
Inputs: hours.
openmeter_usage_anomalyB
Detect usage anomalies: sudden spikes or drops in token usage per org compared to rolling average.
Inputs: hours, baselineHours, spikeThreshold.
openmeter_usage_by_orgC
Per-org usage breakdown: tokens, tool calls, costs by provider and model.
Inputs: hours, orgId.
sentry_get_issueB
Get full Sentry issue detail with latest event stack trace, tags, contexts, and cross-links.
Inputs: issueId (required).
sentry_get_issue_eventsC
Get recent events for a Sentry issue. Detects temporal patterns (burst, steady, regression).
Inputs: issueId (required), limit.
sentry_list_issuesC
List recent Sentry issues for a project. Supports Sentry search syntax.
Inputs: project (required), sort, limit, query.
sentry_project_statsC
Get error rate trends for a Sentry project over a time range.
Inputs: project (required), stat, period, interval.
sentry_resolve_issueC
Update a Sentry issue status: resolve, ignore, or unresolve.
Inputs: action (required), issueId (required), ignoreDuration.
sentry_search_by_traceB
Find all Sentry errors linked to a specific OTel trace ID across projects.
Inputs: traceId (required), project.
suggest_alert_rulesC
Generate Sentry alert rule configurations for a project based on error patterns.
Inputs: project (required), includeMetricAlerts.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Most tools have distinct resource+action targets (list/get/resolve issues, stats, health checks), but sentry_search_by_trace and cross_correlate both pivot on trace_id to find related errors and could be confused, and check_conventions vs check_config_health overlap somewhat on observability auditing.
All names are snake_case and mostly verb_noun, which is readable, but the convention is inconsistent: some tools carry service prefixes (sentry_, openmeter_) while others (check_conventions, diagnose_issue, cross_correlate, generate_runbook) do not.
16 tools is slightly heavy but justified given three distinct domains (Sentry, OpenMeter, config/observability auditing) that each need several operations.
Covers Sentry issue lifecycle (list, get, events, resolve), trace search, stats, correlation, runbook/alert generation, plus OpenMeter health/usage/retry and config auditing; minor gaps like issue commenting or alert rule mutation, but core observability workflows are covered.
Maintenance
Related MCP Connectors
MCP server for Sentry - error monitoring, issue tracking, and debugging for AI assistants
MCP observability: analyse MCP server usage, investigate sessions, and instrument MCP servers.
MCP uptime, schema, auth, and SLA receipt monitoring.
Hosted MCP server for AWS cloud spend: service breakdowns, anomalies, savings and forecasts.
Related MCP Servers
- AlicenseBqualityBmaintenanceProvides comprehensive monitoring and observability for MCP server ecosystems with real-time health checks, performance metrics, distributed tracing, anomaly detection, and automated performance reports using OpenTelemetry and Prometheus.221MIT
- FlicenseCqualityDmaintenanceAn MCP server for Prometheus-based monitoring that enables users to query system metrics, resource usage, and PostgreSQL health across multiple environments. It supports both predefined diagnostic checks and custom PromQL execution for comprehensive server monitoring and troubleshooting.12-
- AlicenseNot gradedqualityCmaintenanceAn open source MCP server empowering SREs with intelligent observability, predictive analytics, and AI-driven automation across Kubernetes, OpenShift, and Tekton environments.78 PyPI11Apache 2.0
- FlicenseNot gradedqualityDmaintenanceMCP server for payment reliability tasks including retry strategy recommendation, payment failure simulation, billing guardrail validation, fee leakage detection, and incident summarization.-