{
"markdown": "\n\n# observability-mcp\n\n**The unified observability gateway for AI agents.**\n\nOne MCP server that connects to any observability backend through pluggable connectors,\nnormalizes the data, adds robust anomaly analysis, and provides a web UI for configuration.\n\n*One MCP endpoint, every backend — so an agent triaging an incident asks one normalized\nquestion instead of juggling N vendor servers and their query languages.*\n\n**0/10 → 10/10:** the same 8B local model goes from hallucinating blast-radius answers\nto exactly correct ones once it gets this gateway's topology tools —\n[measured, not asserted](docs/benchmark-astronomy-shop.md).\n\n
\n\n```bash\nnpx @thotischner/observability-mcp # start (UI on :3000)\nclaude mcp add observability --transport http http://localhost:3000/mcp # wire into Claude\n```\n\nTwelve read-only tools (`readOnlyHint: true` on every one) · server-side filter/aggregate\nso agents get **numbers, not haystacks** · [For-Agents guide](https://thotischner.github.io/observability-mcp/for-agents/)\n\n\n\n[](LICENSE)\n[](https://www.npmjs.com/package/@thotischner/observability-mcp)\n[](https://www.npmjs.com/package/@thotischner/observability-mcp)\n[](https://github.com/ThoTischner/observability-mcp/pkgs/container/observability-mcp)\n[](https://github.com/ThoTischner/observability-mcp/actions/workflows/integration.yml)\n[](https://github.com/ThoTischner/observability-mcp/stargazers)\n[](https://modelcontextprotocol.io)\n[](https://artifacthub.io/packages/search?repo=observability-mcp)\n\n\nAll badges — CI, Helm, supply chain (cosign / SBOM / SLSA / provenance)
\n
\n\n[](https://github.com/ThoTischner/observability-mcp/actions/workflows/helm-integration.yml)\n[](https://www.typescriptlang.org/)\n[](./helm/observability-mcp)\n[](https://docs.npmjs.com/generating-provenance-statements)\n[](SECURITY.md#container-image--ghcr--scanned--cosign-signed--syft-sbom)\n[](SECURITY.md#container-image--ghcr--scanned--cosign-signed--syft-sbom)\n[](SECURITY.md#container-image--ghcr--scanned--cosign-signed--syft-sbom)\n[](SECURITY.md#container-image--ghcr--scanned--cosign-signed--syft-sbom)\n[](https://thotischner.github.io/observability-mcp/hub/)\n\n \n\n\n\n
\n\n---\n\n📖 **Full documentation site:** \n\n🔌 **Open in MCP Inspector** — one-line interactive explorer:\n```bash\nnpx --yes @modelcontextprotocol/inspector \\\n --config <(npx --yes @thotischner/observability-mcp inspector-config)\n```\n\n## Why it matters — measured, not asserted\n\nOn a real Kubernetes-platform-team question (\"which other pods share a node with\n`payment-service` so we know what else falls over if that node goes down?\"), the same\nlocal model produces wildly different answers depending on the tools you hand it:\n\n| Tools available to the agent (llama3.1:8b, n=10) | Cross-namespace blast-radius accuracy |\n|---|:---:|\n| Generic metric + log + service tools | **0 / 10** — hallucinates the wrong entity type (`prometheus`, `loki`, `kubernetes`) |\n| Same model + `get_topology` + `get_blast_radius` | **10 / 10** — exact correct co-tenant list, every iteration |\n\nRaw JSON for both arms, plus three more scenarios (single-service RCA, in-namespace\nblast radius, scenarios where topology does *not* help), live in\n[docs/benchmark-astronomy-shop.md](docs/benchmark-astronomy-shop.md). The harness is in\n[`scripts/benchmark-rca.mjs`](scripts/benchmark-rca.mjs); re-run with `make benchmark-up && make benchmark-run`.\n\nWe don't claim universal speedup — the doc spells out exactly where the topology tools\nhelp (graph-shaped questions) and where they don't (pure single-metric drill-downs).\n\n---\n\n## Try it in 10 seconds\n\n```bash\nnpx @thotischner/observability-mcp\n# then open http://localhost:3000\n```\n\nWire it into Claude Code with one CLI call:\n\n```bash\nclaude mcp add observability --transport http http://localhost:3000/mcp\n```\n\n…or commit it to your repo as `.mcp.json` (works the same in Claude Desktop / Cursor):\n\n```json\n{\n \"mcpServers\": {\n \"observability\": {\n \"transport\": { \"type\": \"http\", \"url\": \"http://localhost:3000/mcp\" }\n }\n }\n}\n```\n\nThe server starts with **zero sources**. Add Prometheus/Loki via the Web UI or `PROMETHEUS_URL` / `LOKI_URL` env vars.\n\n> If you'd rather have the snippets above printed by a Make target — including\n> custom-host / custom-port substitution — use `make connect-claude-code` or\n> `make connect-cursor`. `make doctor` round-trips a real MCP handshake against\n> a running server, reports the live governance posture (auth mode, redaction,\n> audit-log persistence, per-identity rate cap), and tells you what to fix if\n> it can't.\n\n> **Multi-user / production?** See [docs/access-control.md](docs/access-control.md)\n> for the opt-in basic-mode login + RBAC + audit log + per-identity rate limit\n> setup. All off by default; the demo above is unchanged.\n>\n> **SSO via OIDC?** `make demo-oidc` boots a Keycloak + an OIDC-flavored\n> mcp-server on port **3001** with three pre-provisioned users\n> (`admin` / `operator` / `viewer`, password = username, DEMO ONLY).\n> See [docs/auth-oidc.md](docs/auth-oidc.md) for production Keycloak /\n> Authentik / Auth0 / Azure AD setups.\n>\n> **External RBAC via OPA?** `make demo-opa` boots an Open Policy Agent\n> with an example Rego policy + an OPA-backed mcp-server on port **3002**.\n> See [docs/policy-engines.md](docs/policy-engines.md) for the\n> built-in / file / OPA backend trade-offs and migration paths.\n>\n> **Curated MCP Products?** Set `OMCP_PRODUCTS_FILE` to a YAML catalog\n> ([`config/products.yaml.example`](mcp-server/config/products.yaml.example))\n> and ship per-tenant/per-agent tool bundles instead of \"everything,\n> all the time\". RBAC-gated, audited, hot-editable. Details in\n> [docs/products.md](docs/products.md).\n\nWant the full chaos-engineering demo (Prometheus + Loki + 3 example services + the autonomous agent)? Clone and run:\n\n```bash\nmake demo # equivalent to: docker compose --profile demo up --build --wait\n```\n\nOr run the **sovereign quickstart** — one command, fully on-prem, zero\nexternal calls: it starts the stack, injects a real incident, and shows\nside by side what an agent gets *without* vs *with* the analysis layer (a\nwall of raw numbers vs a scored verdict that pinpoints the culprit). The\noptional agent reasons over it with a **local** model (Ollama):\n\n```bash\nmake demo-sovereign\n```\n\nSee `make help` for all canonical workflows.\n\n## Why?\n\nEvery 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.\n\n**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.\n\n**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.\n\n## Features\n\n- **🔍 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)\n- **Unified gateway** — Single MCP endpoint for all your observability backends.\n- **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.\n- **Web UI** — Sources, services, health monitoring, configuration. Real-time, dark theme.\n- **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.\n- **Loki label fallback** — Discovers services through `service_name` / `service` / `job` / `app` / `container`, including Docker-shipped streams with leading slashes.\n- **Pluggable connectors** — One interface, any query language (PromQL, LogQL, Flux, KQL...). See [docs/connectors.md](docs/connectors.md).\n- **Auth & TLS** — Basic, Bearer, custom CA, mTLS. See [docs/auth-and-tls.md](docs/auth-and-tls.md).\n- **Multi-backend** — Multiple instances of the same type, no problem.\n\n## Inspect — see, learn & enforce agent behavior\n\nYou handed an agent (or a CI bot, or a leaked credential) a key to your\nobservability backends. **Inspect** answers the question RBAC can't: *is this\ncall **normal** for this identity, compared to what it has actually been doing?*\n\n[](docs/screenshots/inspect-flows.png)\n\nIt borrows AppArmor's learning workflow and a service-mesh traffic view (think\nKiali, for agent tool calls):\n\n```\n OFF ──▶ OBSERVE ──▶ DRY-RUN (complain) ──▶ ENFORCE\n │ │ │\n record calls compute what WOULD be block calls that\n only (zero blocked, but still allow fall outside the\n risk, default) — review before enforcing accepted profile\n```\n\n- **Flows** — a live **Identities → Tools → Backends** graph. Edge thickness is\n call volume; colour is allowed / deviation / blocked. Click any node to drill\n into the real calls, the argument-shape distribution, and turn an observed\n edge straight into a rule.\n- **Profile** — the learning loop: hit **\"Learn from traffic\"**, review the\n suggested rules (`anonymous → query_logs · service ∈ {payment-service}` —\n learned from N calls), and accept / edit / reject each one. Only accepted\n rules ever gate traffic.\n- **Deviations** — every call that fell outside the profile: who, which tool,\n what was unusual — one click to accept into the profile or confirm an anomaly.\n\nPrivacy by design: Inspect stores argument **shapes**, never raw payloads, and\nruns everything through the gateway's redaction layer first. It makes **no\noutbound calls** — the air-gapped guarantee is unchanged.\n\n**OSS vs. licensed:** `observe` and `dry-run` — the live graph, learning a\nprofile, seeing would-block deviations — are **free**. Active **`enforce`**\nblocking is an entitled control (shown with a 🔒 in the UI). Visibility is free;\nenforcement is the licensed capability. Full design:\n[docs/inspect.md](docs/inspect.md).\n\n## Detection quality\n\nThe anomaly engine is backtested against a labelled synthetic suite covering\nslow ramps (memory-leak-toward-OOM), spikes, step changes, stable noise,\ntransient blips, one-sided recoveries, daily-seasonal patterns, and a\ndeliberately ambiguous low-SNR \"hard\" tier. Scored as a CI gate\n([`backtest.test.ts`](mcp-server/src/analysis/backtest.test.ts)) — these\nnumbers are regenerated from that suite, not hand-written:\n\n| Cases | Precision | Recall | F1 |\n|------:|----------:|-------:|---:|\n| 64 | 100.0% | 87.5% | 93.3% |\n\nPrecision is 100% (no spurious alerts); the recalled misses are by design at\nthe noise floor of the hard tier. The suite is deterministic and a detector\nregression fails CI. Reproduce locally:\n\n```bash\ndocker run --rm -w /app -v \"$(pwd)/mcp-server:/app\" node:20-alpine \\\n sh -c \"npm i --silent && npx tsx --test src/analysis/backtest.test.ts\"\n```\n\n## Screenshots\n\n| Inspect — flow graph | Inspect — learn a profile |\n|---|---|\n| [](docs/screenshots/inspect-flows.png) | [](docs/screenshots/inspect-profile.png) |\n\n| Dashboard | Service health | Connector hub |\n|---|---|---|\n| [](docs/screenshots/dashboard.png) | [](docs/screenshots/health.png) | [](docs/screenshots/connectors.png) |\n\n## Architecture\n\n```mermaid\ngraph TB\n Agent[\"AI Agent
Claude, Ollama, etc.\"]\n\n subgraph MCP [\"observability-mcp :3000\"]\n Tools[\"12 MCP Tools\"]\n Analysis[\"Analysis Engine
Robust stats, Health Scoring, Correlation\"]\n UI[\"Web UI\"]\n end\n\n subgraph Connectors [\"Pluggable Connectors\"]\n Prom[\"Prometheus
PromQL — metrics\"]\n Loki[\"Loki
LogQL — logs\"]\n K8s[\"Kubernetes
watch — topology\"]\n Next[\"Your Backend
Any query language\"]\n end\n\n Agent <-->|\"MCP
Streamable HTTP\"| Tools\n Tools --- Analysis\n Tools --- UI\n MCP --> Prom & Loki & K8s & Next\n\n style MCP fill:#1a1a2e,stroke:#58a6ff,color:#fff\n style Connectors fill:#0d1117,stroke:#3fb950,color:#fff\n style Agent fill:#58a6ff,stroke:#58a6ff,color:#000\n style Next fill:#0d1117,stroke:#3fb950,color:#8b949e,stroke-dasharray: 5 5\n```\n\n## Repo layout\n\n```\nmcp-server/ # the product — server, Web UI, analysis engine, built-in plugins\nhelm/ # ArtifactHub-grade Helm chart\ndocs/ # configuration, auth, plugin architecture, airgapped deployment, ...\nexamples/ # demo material — agent, example services, Prometheus+Loki configs\n```\n\n`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.\n\n## Installation\n\n| Method | Command | Best for |\n|--------|---------|----------|\n| **npm** | `npx @thotischner/observability-mcp` | Local dev, Node toolchains, zero install |\n| **Docker (GHCR)** | `docker run -p 3000:3000 ghcr.io/thotischner/observability-mcp:latest` | Production hosts, isolation |\n| **Helm** | `helm repo add observability-mcp https://thotischner.github.io/observability-mcp/`
`helm install observability-mcp observability-mcp/observability-mcp` | Kubernetes |\n| **From source** | `git clone … && make demo` | Full POC with example services and chaos |\n| **CLI (`omcp`)** | `npm i -g @thotischner/observability-mcp` | Managing connectors, the demo stack & Helm from the terminal — see [CLI](#cli-omcp) |\n\nGHCR 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.\n\n### Helm chart\n\nThe 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.\n\n```bash\nhelm repo add observability-mcp https://thotischner.github.io/observability-mcp/\nhelm repo update\nhelm install observability-mcp observability-mcp/observability-mcp \\\n --set sources.prometheusUrl=http://prometheus.monitoring.svc.cluster.local:9090 \\\n --set sources.lokiUrl=http://loki.logging.svc.cluster.local:3100\n```\n\n```yaml\n# docker-compose snippet\nservices:\n observability-mcp:\n image: ghcr.io/thotischner/observability-mcp:latest\n ports: [\"3000:3000\"]\n environment:\n PROMETHEUS_URL: http://prometheus:9090\n LOKI_URL: http://loki:3100\n volumes:\n - ./mcp-config:/home/node/.observability-mcp\n restart: unless-stopped\n```\n\nFor full configuration — paths, env vars, `${VAR}` substitution, complete `sources.yaml` reference — see [docs/configuration.md](docs/configuration.md).\n\n## Quick Start\n\n### Option A: Standalone (your own backends)\n\n```bash\nnpx @thotischner/observability-mcp\n```\n\nThen open the Web UI at `http://localhost:3000`, click **Sources → + Add Source**, point at your Prometheus/Loki URLs. Or skip the UI:\n\n```bash\nPROMETHEUS_URL=http://localhost:9090 LOKI_URL=http://localhost:3100 \\\n npx @thotischner/observability-mcp\n```\n\n### Option B: Grafana Cloud\n\nGrafana 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*.\n\n```yaml\n# ~/.observability-mcp/sources.yaml\nsources:\n - name: grafana-cloud-prom\n type: prometheus\n url: https://prometheus-prod-XX-prod-eu-west-X.grafana.net/api/prom\n enabled: true\n auth:\n type: basic\n username: \"${GRAFANA_PROM_USER}\" # numeric instance ID\n password: \"${GRAFANA_TOKEN}\"\n - name: grafana-cloud-loki\n type: loki\n url: https://logs-prod-XXX.grafana.net\n enabled: true\n auth:\n type: basic\n username: \"${GRAFANA_LOKI_USER}\" # different from Prom!\n password: \"${GRAFANA_TOKEN}\"\n```\n\n```bash\nGRAFANA_PROM_USER=… GRAFANA_LOKI_USER=… GRAFANA_TOKEN=glc_… \\\n npx @thotischner/observability-mcp\n```\n\n### Option C: Full demo (Docker Compose with example services)\n\n```bash\ngit clone https://github.com/ThoTischner/observability-mcp.git\ncd observability-mcp\ndocker compose --profile demo up --build\n```\n\nBoots 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`.\n\nThe 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.\n\nWithout `--profile demo`, only `mcp-server` starts — useful when you already run Prometheus/Loki elsewhere and just want to expose them via MCP.\n\n### Option D: Benchmark mode (OpenTelemetry Demo / Astronomy Shop)\n\nFor producing credible RCA numbers against a real microservice workload (~23 services, native OTel instrumentation):\n\n```bash\nmake benchmark-up # clones upstream Astronomy Shop, brings up both stacks\nmake benchmark-run # runs the harness baseline vs topology, writes JSON\nmake benchmark-down # tears down\n```\n\n`make benchmark-up` adds Tempo + an OTel collector bridge under our `--profile benchmark` and orchestrates the upstream stack in a separate compose project, joining their network to ours so Astronomy Shop services push traces into our Tempo. See [docs/benchmark-astronomy-shop.md](docs/benchmark-astronomy-shop.md) and [examples/benchmark/README.md](examples/benchmark/README.md). First-time pull is ~4 GB.\n\n## MCP Tools\n\n| Tool | Signal | Purpose |\n|------|--------|---------|\n| `list_sources` | meta | Discover configured backends and connection status |\n| `list_services` | meta | Discover monitored services across all backends |\n| `query_metrics` | metrics | Query metrics with pre-computed summary stats |\n| `query_logs` | logs | Query logs with error/warning counts and top patterns |\n| `get_service_health` | unified | Health score combining metrics + logs (0–100) |\n| `detect_anomalies` | unified | Cross-signal anomaly detection with robust (median/MAD + trend) analysis |\n| `get_topology` | topology | Return the merged infrastructure graph (resources + edges) from every topology-capable connector, filterable by source/kind/scope |\n| `get_blast_radius` | topology | Pivot on the universal `RUNS_ON` relation — \"if this resource's host fails, who else fails?\". Works for pod→node, vm→hypervisor, container→host |\n\nThe two topology tools require a topology-capable connector. The bundled [Kubernetes connector](docs/kubernetes.md) is the first; future connectors (vCenter, NetBox, …) plug in via the same `isTopologyProvider` interface and emit `kind`/`relation` values from the canonical [topology vocabulary](docs/topology-vocabulary.md).\n\n## Using with Claude Code\n\nConnect Claude Code directly — no agent needed.\n\n**CLI:**\n\n```bash\nclaude mcp add observability --transport http http://localhost:3000/mcp\n```\n\n**Or `.mcp.json` in your project root** (commit-friendly):\n\n```json\n{\n \"mcpServers\": {\n \"observability\": {\n \"transport\": { \"type\": \"http\", \"url\": \"http://localhost:3000/mcp\" }\n }\n }\n}\n```\n\nThen ask Claude in natural language. For example, after triggering chaos in the demo (`curl -X POST http://localhost:8081/chaos/error-spike`):\n\n> *\"Are there any anomalies right now?\"*\n\nClaude calls `detect_anomalies` and finds:\n\n```json\n{\n \"anomalies\": [\n { \"metric\": \"cpu\", \"severity\": \"high\", \"service\": \"payment-service\",\n \"description\": \"cpu is 3.4σ above baseline (18.36 → 37.31)\" },\n { \"metric\": \"request_rate\", \"severity\": \"low\", \"service\": \"payment-service\",\n \"description\": \"request_rate is -1.8σ below baseline (0.08 → 0.04)\" }\n ]\n}\n```\n\n> *\"Show me the error logs for payment-service.\"*\n\nClaude calls `query_logs`:\n\n```json\n{\n \"summary\": {\n \"total\": 11, \"errorCount\": 11,\n \"topPatterns\": [\n \"Request failed: internal error during POST /payments (6x)\",\n \"Request failed: internal error during POST /refunds (4x)\"\n ]\n }\n}\n```\n\nClaude correlates the signals — CPU spike, error logs flooding, request rate halved — and explains the incident in plain language. No PromQL, no LogQL.\n\n## Demo: Chaos Engineering\n\nThree example microservices generate traffic and support chaos injection:\n\n```bash\ncurl -X POST http://localhost:8081/chaos/high-cpu # CPU spike\ncurl -X POST http://localhost:8081/chaos/error-spike # CPU + latency + errors\ncurl -X POST http://localhost:8081/chaos/slow-responses # Latency\ncurl -X POST http://localhost:8081/chaos/memory-leak # OOM logs\ncurl -X POST http://localhost:8081/chaos/reset\n```\n\nThe agent ([docs/agent.md](docs/agent.md)) detects anomalies within 30 seconds and produces an LLM incident analysis if Ollama is running.\n\n## CLI (`omcp`)\n\nA control CLI ships in the same npm package (`omcp` bin) — manage connectors, the demo stack, and Helm installs.\n\nInstall it (or run ad-hoc without installing):\n\n```bash\nnpm i -g @thotischner/observability-mcp # puts `omcp` on your PATH\nomcp --help\n\n# or, no install:\nnpx -p @thotischner/observability-mcp omcp doctor\n```\n\nThen:\n\n```bash\nomcp doctor # check docker / compose / helm / node\nomcp demo up # full demo stack (auto-picks free host ports)\nomcp plugin list # browse the connector hub catalog\nomcp plugin install tempo@1.2.0 --trust-root key.pem # download + verify + extract\nomcp plugin verify ./plugins/tempo --trust-root key.pem # offline audit\nomcp helm upgrade obs -- -n monitoring --set sources.prometheusUrl=http://prom:9090\n```\n\nPlugin install/verify reuse the server's fail-closed signature + integrity\nchecks (offline-capable; `--offline-dir` for airgapped). Extra `helm`\nflags pass through after a literal `--`.\n\n## Docs\n\n- [Configuration](docs/configuration.md) — paths, env vars, `${VAR}` substitution, full `sources.yaml` reference\n- [Authentication & TLS](docs/auth-and-tls.md) — Basic, Bearer, custom CA, mTLS\n- [Management-plane auth (basic mode)](docs/auth-basic.md) — optional login screen + signed session cookies for the Web UI / `/api/*` plane\n- [Log redaction](docs/redaction.md) — PII / secret patterns automatically masked in `query_logs` output before it reaches the agent; opt-out via `OMCP_REDACTION=off`\n- [Access control overview + runbook](docs/access-control.md) — RBAC roles, audit chain, per-identity rate limits, service catalog enrichment, and an investigation runbook for the most common \"who / why\" questions\n- [Prometheus](docs/prometheus.md) — defaults, label resolution, `resolvedSeries`, prom-client compatibility\n- [Loki](docs/loki.md) — label fallback, Docker container slash, managed Loki\n- [Connectors](docs/connectors.md) — write your own backend\n- [Agent](docs/agent.md) — Ollama setup, loop behavior\n- [Troubleshooting](docs/troubleshooting.md) — common pitfalls and fixes\n- [Security](docs/security.md) — automation pipeline, vulnerability reporting, built-in protections\n- [Airgapped deployment](docs/airgapped-deployment.md) — mirroring images, private plugins, GitOps-friendly config\n- [Topology vocabulary](docs/topology-vocabulary.md) — the canonical `kind` / `relation` contract every topology-capable connector emits, plus the warn-only validator\n- [RCA benchmark](docs/benchmark-astronomy-shop.md) — reproducible A/B harness; on a cross-namespace blast-radius question (llama3.1:8b, n=10) the baseline tool set scores 0/10 and hallucinates the wrong entity type, the same model with topology tools scores 10/10 deterministically — see the three-scenarios table for the full honest picture\n- [How this compares to adjacent tools](docs/comparison.md) — source-cited table vs. Datadog Bits AI, HolmesGPT, Robusta — what each is best at and where this fits\n- [Governance access-control gate](docs/enterprise-gate.md) — optional RBAC / catalog / audit behind a signed entitlement token (off by default)\n- [Connector Hub](https://thotischner.github.io/observability-mcp/hub/) — browse versioned, signed connectors (catalog: [`hub/`](hub/README.md))\n- [Use cases](USECASES.md) — five scenarios with the prompts that drive them\n\n## Endpoints\n\n| Service | URL |\n|---------|-----|\n| MCP Server (Streamable HTTP) | http://localhost:3000/mcp |\n| Web UI | http://localhost:3000 |\n| Health API | http://localhost:3000/api/health |\n\nIn the docker-compose demo: Prometheus on `:9090`, Loki on `:3100`. The three example services run as Kubernetes Deployments inside the in-compose k3s and are reachable on the host via the NodePort mapping `:8080–:8082` — same URLs as before the k8s migration, so existing chaos commands keep working.\n\n**Transports:** Streamable HTTP by default (`/mcp`). For stdio-based clients/catalogs (Claude Desktop, Glama's `mcp-proxy`, etc.) run with `--stdio` (or `MCP_TRANSPORT=stdio`) — one MCP server over stdin/stdout, all logs on stderr so the protocol stream stays clean.\n\n## Tech Stack\n\nTypeScript + Node 20, `@modelcontextprotocol/sdk` (Streamable HTTP), Express, Zod, js-yaml, prom-client (example services), Prometheus, Loki, Promtail, Docker Compose, optional Ollama.\n\n## Requirements\n\n- **Standalone:** Node 20+ (or just `npx`)\n- **Docker demo:** Docker + Compose, 4 GB+ RAM (8 GB+ with Ollama)\n- **Optional:** Ollama on the host for the agent's LLM analysis\n\n## Contributing\n\n1. Fork the repo and `docker-compose up --build`.\n2. Pick an issue or open one to discuss your idea.\n3. Submit a PR — all code runs in Docker, no local deps.\n\nIdeas: new connectors (InfluxDB, Elasticsearch, Datadog), additional analysis algorithms, UI improvements.\n\n## License\n\n[Apache License 2.0](LICENSE) — see also [NOTICE](NOTICE).\n\nReleases up to and including the last MIT-licensed version remain available\nunder MIT; subsequent releases are Apache-2.0. Contributions require a\n[Contributor License Agreement](CLA.md).\n\n---\n\n\n\nIf you find this useful, consider giving it a star — it helps others discover the project.\n\n
\n",
"bytes": 29397,
"sha": "25fed4c1f2792c82c6a22e194071f671648a1afed4f100c2b93bdb64f2990ea6",
"repo_slug": "thotischner/observability-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_thotischner_observability_mcp_49df6588/readme"
}