Observability MCP

observability-mcp

The unified observability gateway for AI agents.

One MCP server that connects to any observability backend through pluggable connectors, normalizes the data, adds robust anomaly analysis, and provides a web UI for configuration.

*One MCP endpoint, every backend — so an agent triaging an incident asks one normalized question instead of juggling N vendor servers and their query languages.*

0/10 → 10/10: the same 8B local model goes from hallucinating blast-radius answers to exactly correct ones once it gets this gateway's topology tools — measured, not asserted.

npx @thotischner/observability-mcp                                    # start (UI on :3000)

claude mcp add observability --transport http http://localhost:3000/mcp # wire into Claude

Twelve read-only tools (readOnlyHint: true on every one) · server-side filter/aggregate so agents get numbers, not haystacks · For-Agents guide

All badges — CI, Helm, supply chain (cosign / SBOM / SLSA / provenance)

📖 Full documentation site: https://thotischner.github.io/observability-mcp/

🔌 Open in MCP Inspector — one-line interactive explorer:

npx --yes @modelcontextprotocol/inspector \

--config <(npx --yes @thotischner/observability-mcp inspector-config)

Why it matters — measured, not asserted

On a real Kubernetes-platform-team question ("which other pods share a node with payment-service so we know what else falls over if that node goes down?"), the same local model produces wildly different answers depending on the tools you hand it:

Raw JSON for both arms, plus three more scenarios (single-service RCA, in-namespace blast radius, scenarios where topology does *not* help), live in docs/benchmark-astronomy-shop.md. The harness is in scripts/benchmark-rca.mjs; re-run with make benchmark-up && make benchmark-run.

We don't claim universal speedup — the doc spells out exactly where the topology tools help (graph-shaped questions) and where they don't (pure single-metric drill-downs).

Try it in 10 seconds

npx @thotischner/observability-mcp

then open http://localhost:3000

Wire it into Claude Code with one CLI call:

claude mcp add observability --transport http http://localhost:3000/mcp

…or commit it to your repo as .mcp.json (works the same in Claude Desktop / Cursor):

{

"mcpServers": { "observability": { "transport": { "type": "http", "url": "http://localhost:3000/mcp" } } } }

The server starts with zero sources. Add Prometheus/Loki via the Web UI or PROMETHEUS_URL / LOKI_URL env vars.

If you'd rather have the snippets above printed by a Make target — including

custom-host / custom-port substitution — use make connect-claude-code or

make connect-cursor. make doctor round-trips a real MCP handshake against

a running server, reports the live governance posture (auth mode, redaction,

audit-log persistence, per-identity rate cap), and tells you what to fix if

it can't.

Multi-user / production? See docs/access-control.md

for the opt-in basic-mode login + RBAC + audit log + per-identity rate limit

setup. All off by default; the demo above is unchanged.

SSO via OIDC? make demo-oidc boots a Keycloak + an OIDC-flavored

mcp-server on port 3001 with three pre-provisioned users

(admin / operator / viewer, password = username, DEMO ONLY).

See docs/auth-oidc.md for production Keycloak /

Authentik / Auth0 / Azure AD setups.

External RBAC via OPA? make demo-opa boots an Open Policy Agent

with an example Rego policy + an OPA-backed mcp-server on port 3002.

See docs/policy-engines.md for the

built-in / file / OPA backend trade-offs and migration paths.

Curated MCP Products? Set OMCP_PRODUCTS_FILE to a YAML catalog

(config/products.yaml.example)

and ship per-tenant/per-agent tool bundles instead of "everything,

all the time". RBAC-gated, audited, hot-editable. Details in

docs/products.md.

Want the full chaos-engineering demo (Prometheus + Loki + 3 example services + the autonomous agent)? Clone and run:

make demo   # equivalent to: docker compose --profile demo up --build --wait

Or run the sovereign quickstart — one command, fully on-prem, zero external calls: it starts the stack, injects a real incident, and shows side by side what an agent gets *without* vs *with* the analysis layer (a wall of raw numbers vs a scored verdict that pinpoints the culprit). The optional agent reasons over it with a local model (Ollama):

make demo-sovereign

See make help for all canonical workflows.

Why?

Every observability vendor ships its own MCP server — Prometheus, Grafana, Datadog, Elastic, each siloed. An AI agent triaging an incident across systems must juggle N separate servers and learn each query language (PromQL, LogQL, …). There is no unified abstraction layer.

observability-mcp is that layer: one MCP endpoint that normalizes every backend and answers in plain service/metric/log terms, plus an analysis engine that flags anomalies the agent would otherwise have to reconstruct from raw queries itself.

Who it's for: SRE / platform teams running Prometheus + Loki who use an AI agent (Claude, local LLMs, …) for incident triage. The gateway's leverage is largest when the agent is *not* a frontier model — a smaller or local model that can't reliably hand-write PromQL/LogQL benefits most from normalized tools and pre-computed analysis. A strong frontier model can query raw backends competently on its own; there the value is consistency and the analysis engine, not query convenience. We state this honestly rather than claiming a universal speedup.

Features

• 🔍 Inspect — see, learn & enforce agent behavior — a live service-mesh-style graph of every MCP tool call, an AppArmor-style learning workflow that derives a behavior profile from real traffic, and an enforce mode that blocks calls outside the accepted baseline. Jump to Inspect ↓
• Unified gateway — Single MCP endpoint for all your observability backends.
• Cross-signal analysis — Correlates metrics and logs automatically. Robust anomaly detection (median/MAD baseline, trend detection for slow ramps, warmup + dwell to suppress flapping) and weighted health scoring.
• Web UI — Sources, services, health monitoring, configuration. Real-time, dark theme.
• prom-client defaults — Works out of the box with the standard Node.js Prometheus instrumentation. Dynamic label resolution probes job / service / app / service_name so service filtering Just Works.
• Loki label fallback — Discovers services through service_name / service / job / app / container, including Docker-shipped streams with leading slashes.
• Pluggable connectors — One interface, any query language (PromQL, LogQL, Flux, KQL...). See docs/connectors.md.
• Auth & TLS — Basic, Bearer, custom CA, mTLS. See docs/auth-and-tls.md.
• Multi-backend — Multiple instances of the same type, no problem.

Inspect — see, learn & enforce agent behavior

You handed an agent (or a CI bot, or a leaked credential) a key to your observability backends. Inspect answers the question RBAC can't: *is this call normal for this identity, compared to what it has actually been doing?*

It borrows AppArmor's learning workflow and a service-mesh traffic view (think Kiali, for agent tool calls):

   OFF  ──▶  OBSERVE  ──▶  DRY-RUN (complain)  ──▶  ENFORCE

│ │ │ record calls compute what WOULD be block calls that only (zero blocked, but still allow fall outside the risk, default) — review before enforcing accepted profile

• Flows — a live Identities → Tools → Backends graph. Edge thickness is call volume; colour is allowed / deviation / blocked. Click any node to drill into the real calls, the argument-shape distribution, and turn an observed edge straight into a rule.
• Profile — the learning loop: hit "Learn from traffic", review the suggested rules (anonymous → query_logs · service ∈ {payment-service} — lea