Skip to main content
Glama
Lucid Observability Agent

Lucid Observability Agent

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_id

  • Billing 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-agent

Or 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

  1. Install the package:

npm install lucid-observability-agent
  1. Add 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

SENTRY_AUTH_TOKEN

Yes

Sentry internal integration token (scopes: org:read, project:read, event:read, event:write)

SENTRY_ORG

No

Sentry org slug (overrides config default)

DATABASE_URL

For metering tools

PostgreSQL connection string for OpenMeter outbox

AGENT_CONFIG_PATH

No

Path to custom config JSON (see Configuration)

Tools (16)

Sentry (6)

Tool

Description

sentry_list_issues

List issues by project with Sentry search syntax

sentry_get_issue

Full detail: stack trace, tags, contexts, cross-links

sentry_get_issue_events

Event history with temporal pattern detection

sentry_resolve_issue

Resolve, ignore, or unresolve issues

sentry_search_by_trace

Find errors by OTel trace ID

sentry_project_stats

Error rate trends over time

Diagnosis (2)

Tool

Description

diagnose_issue

Root cause analysis with configurable patterns

cross_correlate

Cross-service error correlation via trace_id/run_id

OpenMeter (4)

Tool

Description

openmeter_outbox_health

Queue depth, dead letters, stuck leases

openmeter_usage_by_org

Per-org token/tool usage breakdown

openmeter_dead_letter_retry

Retry failed dead-letter events

openmeter_usage_anomaly

Spike/drop detection vs rolling baseline

Configuration (2)

Tool

Description

check_config_health

Audit env vars for production readiness

check_conventions

Verify service uses standard conventions

Auto-Fix (2)

Tool

Description

suggest_alert_rules

Generate Sentry alert configs from patterns

generate_runbook

Incident runbook for 10 error categories

Resources (3)

URI

Description

{platform}://conventions

Span names, attribute keys, rules

{platform}://services

Service topology and dependencies

{platform}://sampling

Sampling strategy reference

Prompts (3)

Prompt

Description

triage-issue

6-step issue triage workflow

production-readiness

Full production audit scorecard

incident-response

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

/obs-status

Show observability agent status --- config, services, connections

/obs-check

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 resolution

The 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-agent

When 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 output

Project 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 definitions

License

MIT

Available Tools

16 tools
check_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

    B3.2/5.0

    Scored across 16 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    16 tools is slightly heavy but justified given three distinct domains (Sentry, OpenMeter, config/observability auditing) that each need several operations.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Provides 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.
      22
      1
      MIT
    • F
      license
      C
      quality
      D
      maintenance
      An 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
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      An open source MCP server empowering SREs with intelligent observability, predictive analytics, and AI-driven automation across Kubernetes, OpenShift, and Tekton environments.
      78 PyPI
      11
      Apache 2.0
    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server for payment reliability tasks including retry strategy recommendation, payment failure simulation, billing guardrail validation, fee leakage detection, and incident summarization.
      -