# Observability Mcp > Unified observability gateway for AI agents — one MCP server for Prometheus, Loki, and any backend, with cross-signal anomaly detection and a built-in Web UI. - **Type:** MCP server - **Install:** `agentstack add mcp-thotischner-observability-mcp` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [ThoTischner](https://agentstack.voostack.com/s/thotischner) - **Installs:** 0 - **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure) - **Latest version:** 3.2.1 - **License:** Apache-2.0 - **Upstream author:** [ThoTischner](https://github.com/ThoTischner) - **Source:** https://github.com/ThoTischner/observability-mcp - **Website:** https://www.npmjs.com/package/@thotischner/observability-mcp ## Install ```sh agentstack add mcp-thotischner-observability-mcp ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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](docs/benchmark-astronomy-shop.md). ```bash 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](https://thotischner.github.io/observability-mcp/for-agents/) [](LICENSE) [](https://www.npmjs.com/package/@thotischner/observability-mcp) [](https://www.npmjs.com/package/@thotischner/observability-mcp) [](https://github.com/ThoTischner/observability-mcp/pkgs/container/observability-mcp) [](https://github.com/ThoTischner/observability-mcp/actions/workflows/integration.yml) [](https://github.com/ThoTischner/observability-mcp/stargazers) [](https://modelcontextprotocol.io) [](https://artifacthub.io/packages/search?repo=observability-mcp) All badges — CI, Helm, supply chain (cosign / SBOM / SLSA / provenance) [](https://github.com/ThoTischner/observability-mcp/actions/workflows/helm-integration.yml) [](https://www.typescriptlang.org/) [](./helm/observability-mcp) [](https://docs.npmjs.com/generating-provenance-statements) [](SECURITY.md#container-image--ghcr--scanned--cosign-signed--syft-sbom) [](SECURITY.md#container-image--ghcr--scanned--cosign-signed--syft-sbom) [](SECURITY.md#container-image--ghcr--scanned--cosign-signed--syft-sbom) [](SECURITY.md#container-image--ghcr--scanned--cosign-signed--syft-sbom) [](https://thotischner.github.io/observability-mcp/hub/) --- 📖 **Full documentation site:** 🔌 **Open in MCP Inspector** — one-line interactive explorer: ```bash npx --yes @modelcontextprotocol/inspector \ --config 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](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](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](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`](mcp-server/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](docs/products.md). Want the full chaos-engineering demo (Prometheus + Loki + 3 example services + the autonomous agent)? Clone and run: ```bash 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): ```bash 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 ↓](#inspect--see-learn--enforce-agent-behavior) - **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](docs/connectors.md). - **Auth & TLS** — Basic, Bearer, custom CA, mTLS. See [docs/auth-and-tls.md](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?* [](docs/screenshots/inspect-flows.png) 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}` — learned from N calls), and accept / edit / reject each one. Only accepted rules ever gate traffic. - **Deviations** — every call that fell outside the profile: who, which tool, what was unusual — one click to accept into the profile or confirm an anomaly. Privacy by design: Inspect stores argument **shapes**, never raw payloads, and runs everything through the gateway's redaction layer first. It makes **no outbound calls** — the air-gapped guarantee is unchanged. **OSS vs. licensed:** `observe` and `dry-run` — the live graph, learning a profile, seeing would-block deviations — are **free**. Active **`enforce`** blocking is an entitled control (shown with a 🔒 in the UI). Visibility is free; enforcement is the licensed capability. Full design: [docs/inspect.md](docs/inspect.md). ## Detection quality The anomaly engine is backtested against a labelled synthetic suite covering slow ramps (memory-leak-toward-OOM), spikes, step changes, stable noise, transient blips, one-sided recoveries, daily-seasonal patterns, and a deliberately ambiguous low-SNR "hard" tier. Scored as a CI gate ([`backtest.test.ts`](mcp-server/src/analysis/backtest.test.ts)) — these numbers are regenerated from that suite, not hand-written: | Cases | Precision | Recall | F1 | |------:|----------:|-------:|---:| | 64 | 100.0% | 87.5% | 93.3% | Precision is 100% (no spurious alerts); the recalled misses are by design at the noise floor of the hard tier. The suite is deterministic and a detector regression fails CI. Reproduce locally: ```bash docker run --rm -w /app -v "$(pwd)/mcp-server:/app" node:20-alpine \ sh -c "npm i --silent && npx tsx --test src/analysis/backtest.test.ts" ``` ## Screenshots | Inspect — flow graph | Inspect — learn a profile | |---|---| | [](docs/screenshots/inspect-flows.png) | [](docs/screenshots/inspect-profile.png) | | Dashboard | Service health | Connector hub | |---|---|---| | [](docs/screenshots/dashboard.png) | [](docs/screenshots/health.png) | [](docs/screenshots/connectors.png) | ## Architecture ```mermaid graph TB Agent["AI AgentClaude, Ollama, etc."] subgraph MCP ["observability-mcp :3000"] Tools["12 MCP Tools"] Analysis["Analysis EngineRobust stats, Health Scoring, Correlation"] UI["Web UI"] end subgraph Connectors ["Pluggable Connectors"] Prom["PrometheusPromQL — metrics"] Loki["LokiLogQL — logs"] K8s["Kuberneteswatch — topology"] Next["Your BackendAny query language"] end Agent |"MCPStreamable HTTP"| Tools Tools --- Analysis Tools --- UI MCP --> Prom & Loki & K8s & Next style MCP fill:#1a1a2e,stroke:#58a6ff,color:#fff style Connectors fill:#0d1117,stroke:#3fb950,color:#fff style Agent fill:#58a6ff,stroke:#58a6ff,color:#000 style Next fill:#0d1117,stroke:#3fb950,color:#8b949e,stroke-dasharray: 5 5 ``` ## Repo layout ``` mcp-server/ # the product — server, Web UI, analysis engine, built-in plugins helm/ # ArtifactHub-grade Helm chart docs/ # configuration, auth, plugin architecture, airgapped deployment, ... examples/ # demo material — agent, example services, Prometheus+Loki configs ``` `mcp-server/` is what you install. Everything under `examples/` is opt-in via `docker compose --profile demo` — it's how the repo demos chaos detection end-to-end, but production deployments don't need any of it. ## Installation | Method | Command | Best for | |--------|---------|----------| | **npm** | `npx @thotischner/observability-mcp` | Local dev, Node toolchains, zero install | | **Docker (GHCR)** | `docker run -p 3000:3000 ghcr.io/thotischner/observability-mcp:latest` | Production hosts, isolation | | **Helm** | `helm repo add observability-mcp https://thotischner.github.io/observability-mcp/``helm install observability-mcp observability-mcp/observability-mcp` | Kubernetes | | **From source** | `git clone … && make demo` | Full POC with example services and chaos | | **CLI (`omcp`)** | `npm i -g @thotischner/observability-mcp` | Managing connectors, the demo stack & Helm from the terminal — see [CLI](#cli-omcp) | GHCR is multi-arch (amd64 + arm64). Available tags: `latest`, `main`, `X.Y.Z`, `X.Y`, `X`, `sha-`. Note: the leading `v` is stripped from semver tags. ### Helm chart The chart ships with Deployment, Service, optional Ingress/PVC/HPA, NetworkPolicy, ServiceMonitor (auto-gated on the Prometheus Operator CRD), `helm test` connection probe, and `values.schema.json` validation. ArtifactHub-grade annotations. See [`helm/observability-mcp/`](./helm/observability-mcp/) for the full values reference, or the [airgapped deployment guide](docs/airgapped-deployment.md) for a hardened production example. ```bash helm repo add observability-mcp https://thotischner.github.io/observability-mcp/ helm repo update helm install observability-mcp observability-mcp/observability-mcp \ --set sources.prometheusUrl=http://prometheus.monitoring.svc.cluster.local:9090 \ --set sources.lokiUrl=http://loki.logging.svc.cluster.local:3100 ``` ```yaml # docker-compose snippet services: observability-mcp: image: ghcr.io/thotischner/observability-mcp:latest ports: ["3000:3000"] environment: PROMETHEUS_URL: http://prometheus:9090 LOKI_URL: http://loki:3100 volumes: - ./mcp-config:/home/node/.observability-mcp restart: unless-stopped ``` For full configuration — paths, env vars, `${VAR}` substitution, complete `sources.yaml` reference — see [docs/configuration.md](docs/configuration.md). ## Quick Start ### Option A: Standalone (your own backends) ```bash npx @thotischner/observability-mcp ``` Then open the Web UI at `http://localhost:3000`, click **Sources → + Add Source**, point at your Prometheus/Loki URLs. Or skip the UI: ```bash PROMETHEUS_URL=http://localhost:9090 LOKI_URL=http://localhost:3100 \ npx @thotischner/observability-mcp ``` ### Option B: Grafana Cloud Grafana Cloud uses Basic Auth with your numeric instance ID as username and an API token as password. The instance ID for Prometheus and Loki is different — find both in *Connections → Data sources*. ```yaml # ~/.observability-mcp/sources.yaml sources: - name: grafana-cloud-prom type: prometheus url: https://prometheus-prod-XX-prod-eu-west-X.grafana.net/api/prom enabled: true auth: type: basic username: "${GRAFANA_PROM_USER}" # numeric instance ID password: "${GRAFANA_TOKEN}" - name: grafana-cloud-loki type: loki url: https://logs-prod-XXX.grafana.net enabled: true auth: type: basic username: "${GRAFANA_LOKI_USER}" # different from Prom! password: "${GRAFANA_TOKEN}" ``` ```bash GRAFANA_PROM_USER=… GRAFANA_LOKI_USER=… GRAFANA_TOKEN=glc_… \ npx @thotischner/observability-mcp ``` ### Option C: Full demo (Docker Compose with example services) ```bash git clone https://github.com/ThoTischner/observability-mcp.git cd observability-mcp docker compose --profile demo up --build ``` Boots a single-node **k3s** cluster, builds the three example services and runs them as Kubernetes Deployments inside k3s, plus Prometheus, Loki, Promtail, the MCP server and the agent on the docker-compose side. Open `http://localhost:3000`. The same Deployments that Prometheus scrapes and Loki receives logs from are also what the topology graph shows — so the agent can correlate a metric/log anomaly with its underlying host using `get_blast_radius`. Chaos endpoints stay on `localhost:8080/8081/8082` (mapped to the k3s NodePorts) so existing scripts and demo videos keep working unchanged. Without `--profile demo`, only `mcp-server` starts — useful when you already run Prometheus/Loki elsewhere and just want to expose them via MCP. ### Option D: B … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [ThoTischner](https://github.com/ThoTischner) - **Source:** [ThoTischner/observability-mcp](https://github.com/ThoTischner/observability-mcp) - **License:** Apache-2.0 - **Homepage:** https://www.npmjs.com/package/@thotischner/observability-mcp Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v3.2.1 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **3.2.1** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-thotischner-observability-mcp - Seller: https://agentstack.voostack.com/s/thotischner - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.