log10x-mcp 1.0.0 → 1.6.2

package/LICENSE

@@ -1,21 +1,190 @@
-MIT License
-
-Copyright (c) 2026 Log10x
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025-2026 Log10x, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,22 +1,136 @@
 # Log10x MCP Server
 
-Per-pattern log cost attribution for AI assistants. Ask Claude (or any MCP-compatible AI) "why did our log costs spike this week?" and get an instant, dollar-ranked answer powered by pre-aggregated Prometheus metrics.
+Observability memory for your logs, exposed to AI assistants. Ask Claude (or any MCP-compatible AI) *"why did our log costs spike this week?"*, *"triage these 3000 events"*, *"what's causing the payments-svc error spike"*, or *"pull all payment_retry events for acme-corp from Jan 15 through Apr 15"* — and get structured answers backed by stable per-pattern identity, not best-effort clustering.
 
 ## What it does
 
-Log10x pre-aggregates per-pattern byte metrics inline, before logs hit any SIEM. This MCP server exposes that data to AI assistants as a set of tools:
+Log10x fingerprints every log line into a stable `templateHash` — a structural identity that stays constant across deploys, restarts, pod names, timestamps, and request IDs. That identity is the key to a per-pattern Prometheus time series (volume + cost) and, optionally, a Bloom-indexed S3 archive of the raw events. This MCP server exposes both surfaces to AI assistants as a set of tools:
 
-| Tool | Answers |
-|---|---|
-| `log10x_cost_drivers` | "Why did our log costs spike?" — dollar-ranked patterns with before→after deltas |
-| `log10x_event_lookup` | "What is this Payment Gateway pattern?" — cost breakdown + AI classification |
-| `log10x_savings` | "How much are we saving?" — per-app savings with annual projection |
-| `log10x_pattern_trend` | "When did this pattern start spiking?" — time series + sparkline |
-| `log10x_services` | "What services are we monitoring?" — volume + cost by service |
-| `log10x_exclusion_filter` | "How do I drop this in Datadog?" — config snippets for 14 vendors |
-| `log10x_dependency_check` | "Anything depending on this before I drop it?" — SIEM dependency scan |
+### Cost attribution and daily-habit tools
+
+| Tool | Answers | Tier |
+|---|---|---|
+| `log10x_cost_drivers` | "Why did our log costs spike?" — dollar-ranked patterns with before→after deltas, keyed by stable templateHash (Datadog Log Patterns re-cluster per query and can't do this honestly) | Reporter |
+| `log10x_event_lookup` | "What is this single log line?" — cost breakdown + AI classification | Reporter |
+| `log10x_pattern_trend` | "When did this pattern start spiking?" — time series + sparkline | Reporter |
+| `log10x_top_patterns` | "What's expensive right now?" — loudest patterns by current cost | Reporter |
+| `log10x_list_by_label` | "Cost by namespace / severity / tenant?" — group-by ranking | Reporter |
+| `log10x_services` | "What services are we monitoring?" — volume + cost by service | Reporter |
+| `log10x_discover_labels` | "What labels can I filter on?" — label universe for the session | Reporter |
+| `log10x_savings` | "How much are we saving?" — per-app savings with annual projection | Reporter |
+| `log10x_dependency_check` | "Anything depending on this before I drop it?" — SIEM dependency scan | None |
+| `log10x_exclusion_filter` | "How do I drop this in Datadog?" — config snippets for 14 vendors | None |
+
+### Investigation, triage, and archive tools (v1.3)
+
+| Tool | Answers | Tier |
+|---|---|---|
+| `log10x_investigate` | "Why is this spiking?" — single-call root-cause: anchor resolution, trajectory shape detection (acute-spike vs drift), cross-pattern lag correlation, causal chain with stat/lag/chain confidence sub-scores, drift cohort analysis, two-stage Retriever fallback, verification commands. Surfaces log-only signals (pool saturation, cache evictions, retry amplification) that APM structurally cannot see. | Reporter |
+| `log10x_resolve_batch` | "Triage these events" — paste a file / array / text dump of raw log lines and get per-pattern frequency, severity, variable concentration, and next-action suggestions. Runs via the Log10x paste endpoint; works at any tier including CLI-only. | None |
+| `log10x_retriever_query` | "Get me the actual events" — direct retrieval from the Retriever archive by templateHash with JS filter expressions over event payloads. Queries the customer's own S3 via pre-computed Bloom filters. Answers forensic, audit, and out-of-retention retrieval. | Retriever |
+| `log10x_backfill_metric` | "Create a new Datadog metric backfilled with 90 days of history" — pulls historical events from the Retriever, aggregates into a bucketed time series, emits to the destination TSDB with historical timestamps preserved. Datadog + Prometheus remote_write supported today. | Retriever |
+
+All tools query `prometheus.log10x.com` (for Reporter-tier tools) over HTTPS, with the same `X-10X-Auth` header used by the rest of the Log10x stack. No log scanning; sub-second at any scale.
+
+## ROI examples — three real flows
+
+These are real round-trips against the Log10x demo environment, captured during development. Every tool call below is verbatim what the model would produce; outputs are abbreviated for the README.
+
+### 1. "Why is checkout-svc cost up?" (`log10x_cost_drivers`)
+
+**Prompt**: *"Why did checkout cost spike this week?"*
+
+**Tool call**: `log10x_cost_drivers({ service: "cart", timeRange: "7d" })`
+
+**Output** (abbreviated):
+
+```
+cart — $137 → $38K/wk (4 cost drivers)
+
+#1  cart cartstore ValkeyCartStore     $51 → $13K/wk   INFO  13.3B events
+#2  shipping service Post shipping...  $34 → $12K/wk   CRIT  1.6B events
+#3  GetCartAsync called with userId    $34 → $8.7K/wk        8.7B events
+#4  AddItemAsync called with...        $18 → $4.6K/wk        4.2B events
+
+4 drivers = 49% of increase · 2442 other patterns
+
+**Next actions**:
+  - call `log10x_investigate({ starting_point: 'cart_cartstore_ValkeyCartStore' })` to trace the cause of the $13K delta on this pattern.
+  - call `log10x_dependency_check({ pattern: '...' })` before muting or dropping — blast-radius safety.
+```
+
+The next-action hints in the output literally tell the model what to do next. No prompt engineering required.
+
+### 2. "What's broken in payments-svc?" (`log10x_investigate`)
+
+**Prompt**: *"Investigate kafka — there's an alert firing."*
+
+**Tool call**: `log10x_investigate({ starting_point: "kafka", window: "1h" })`
+
+**Output** (abbreviated 8-link causal chain):
+
+```
+## Investigation: kafka, last 1h
+
+**Anchor**: cluster_metadata_Wrote_producer_snapshot... (resolved from service_name)
+**Service**: kafka
+**Inflection**: 2026-04-14T00:19:52Z UTC
+**Shape**: acute spike
+**Reporter tier**: edge
 
-The server queries `prometheus.log10x.com` over HTTPS. No log scanning, sub-second at any scale.
+### Most likely root cause
+
+Pattern: cluster_metadata_dir_tmp_kafka_logs_Rolled_new_segment...
+Confidence: 43% (stat:1.00 lag:0.43 chain:1.00)
+Why: peaked 300s before the anchor, magnitude 1.4× baseline.
+
+### Causal chain
+
+1. cluster_metadata_dir_tmp_kafka_logs_Rolled... — peaked T-300s
+2. Successfully_wrote_snapshot_org_apache_kafka...  — peaked T-300s
+3. opentelemetry_javaagent_shaded_instrumentation... — peaked T-300s
+... (8 links total, each with stat × lag × chain confidence sub-scores)
+
+### Suggested verification commands
+
+gh api /repos/<owner>/kafka/commits?since=...&until=...
+kubectl get events -n kafka --since=Xm
+dog metric query "avg:trace.kafka.requests{*} by {resource_name}" --from ...
+```
+
+The full causal chain comes back in one tool call. The model doesn't need to compose. The verification commands are pre-substituted with the inflection timestamp so the user can paste them directly.
+
+### 3. "Triage this Slack paste" (`log10x_resolve_batch`)
+
+**Prompt**: *"My teammate dumped these 12 lines from order-processing-svc into Slack — what's happening?"*
+
+**Tool call**: `log10x_resolve_batch({ source: "text", text: "..." })`
+
+**Output** (abbreviated):
+
+```
+## Batch Triage
+
+12 events, resolved into 3 distinct patterns. Templater wall time: 6.4s. Execution: Log10x paste endpoint.
+
+**Severity mix**: INFO: 7 · ERROR: 4 · WARN: 1
+
+### Top 3 patterns by interestingness
+
+**#1  checkout_svc_tenant_acme_corp_order_status_failed_reason_payment_gateway**  · 4 events (33% of batch) · interestingness 0.47
+severity: ERROR
+
+Variable concentration (top values within this batch):
+  - timestamp · 4 distinct · `1776067923000` 25%, `1776067925000` 25%, `1776067928000` 25%
+  - order · 4 distinct · `12347` 25%, `12349` 25%, `12352` 25%
+
+**Next actions**:
+  - call `log10x_investigate({ starting_point: '...' })` for historical correlation (requires Reporter tier).
+  - call `log10x_retriever_query({ pattern: '...', filters: ["event.order === \"12347\""] })` to retrieve all historical events concentrated on order=12347 (requires Retriever tier).
+  - native Datadog follow-up: `dog log search '@order:"12347"' --from now-24h` — filters to the dominant variable concentration directly in the SIEM.
+```
+
+Every pattern is ranked by an interestingness score (severity-weighted); the dominant variable is identified; ready-to-paste next-action commands are pre-constructed for both Log10x tools and the customer's SIEM. The model just needs to relay the output and ask which path the user wants to take.
 
 ## Install
 
@@ -31,22 +145,22 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
       "command": "npx",
       "args": ["-y", "log10x-mcp"],
       "env": {
-        "LOG10X_API_KEY": "your-api-key",
-        "LOG10X_ENV_ID": "your-env-id"
+        "LOG10X_API_KEY": "your-api-key"
       }
     }
   }
 }
 ```
 
-Restart Claude Desktop.
+Restart Claude Desktop. The server autodiscovers every env your account can reach (default + any shared with you) — pass `environment: "<nickname>"` on any tool call to switch between them.
+
+If `LOG10X_API_KEY` is omitted, the MCP boots in **demo mode** against the public Log10x demo env (read-only). Run `log10x_signin` and the LLM will walk you through the GitHub Device Flow — it mints a real key, writes it to `~/.log10x/credentials`, and hot-reloads without an MCP-host restart.
 
 ### Claude Code
 
 ```bash
 claude mcp add --transport stdio \
   --env LOG10X_API_KEY=your-api-key \
-  --env LOG10X_ENV_ID=your-env-id \
   log10x -- npx -y log10x-mcp
 ```
 
@@ -54,34 +168,22 @@ Verify with `/mcp`.
 
 ### Cursor / Windsurf / other MCP clients
 
-Same pattern — add an `mcpServers` entry with `"command": "npx"`, `"args": ["-y", "log10x-mcp"]`, and the two env vars.
+Same pattern — add an `mcpServers` entry with `"command": "npx"`, `"args": ["-y", "log10x-mcp"]`, and `LOG10X_API_KEY`.
 
 ## Get your credentials
 
-1. Log into [console.log10x.com](https://console.log10x.com)
-2. Open Profile → API Settings
-3. Copy your **API Key** and **Environment ID**
-4. (Optional) Set your **Analyzer Cost** ($/GB for your SIEM) — the server reads this automatically
+Two options:
 
-## Multi-environment setup
+1. **Sign in via GitHub**: launch the MCP without `LOG10X_API_KEY` set, then ask the LLM to "sign in to Log10x". `log10x_signin` runs the GitHub Device Flow, mints an API key, and saves it to `~/.log10x/credentials` — works across every MCP host on the same machine.
+2. **Console**: log into [console.log10x.com](https://console.log10x.com) → Profile → API Settings → copy your API Key. (Optional: set your **Analyzer Cost** ($/GB for your SIEM) on that page — the server reads it automatically.)
 
-To query multiple Log10x environments from a single MCP client, use `LOG10X_ENVS` instead of the single-env variables:
+## Multi-environment access
 
-```json
-{
-  "mcpServers": {
-    "log10x": {
-      "command": "npx",
-      "args": ["-y", "log10x-mcp"],
-      "env": {
-        "LOG10X_ENVS": "[{\"nickname\":\"prod\",\"apiKey\":\"...\",\"envId\":\"...\"},{\"nickname\":\"staging\",\"apiKey\":\"...\",\"envId\":\"...\"}]"
-      }
-    }
-  }
-}
-```
+Two patterns, depending on what you need:
+
+**Same account, multiple envs** (e.g., your account owns prod, staging, dev). Nothing special to configure — the MCP autodiscovers all envs your account can reach via `GET /api/v1/user`. Pass `environment: "<nickname>"` on any tool call, or just say "check staging costs" and the LLM routes there. The chosen env sticks for follow-up calls until you switch again.
 
-Then ask "check prod costs" or "what's spiking in staging?" — the AI routes to the right environment via the `environment` parameter.
+**Multiple accounts** (e.g., a consultant accessing customer envs). The Log10x backend supports per-env permission sharing (OWNER / WRITE / READ). Have the env owner grant your account READ on their env from the console — it then shows up in your `/api/v1/user` response automatically, no client-side multi-credential setup needed. If you genuinely need parallel access from distinct API keys, register one MCP server per account in your host config with distinct server names.
 
 ## Usage
 
@@ -123,15 +225,86 @@ cart — $103 → $13K/wk (3 cost drivers)
 
 ## Environment variables
 
+### Reporter-tier (required for cost, trend, and investigate tools)
+
 | Variable | Required | Description |
 |---|---|---|
-| `LOG10X_API_KEY` | Yes (single-env) | Your Log10x API key |
-| `LOG10X_ENV_ID` | Yes (single-env) | Your Log10x environment ID |
-| `LOG10X_ENVS` | Yes (multi-env) | JSON array of `{nickname, apiKey, envId}` |
+| `LOG10X_API_KEY` | No | Your Log10x API key. Omit to boot in demo mode + use `log10x_signin` to mint one via GitHub. The env list is autodiscovered from `GET /api/v1/user` — no env-id pinning needed. |
 | `LOG10X_API_BASE` | No | API base URL (default: `https://prometheus.log10x.com`) |
 
+### Pasted-batch triage (`log10x_resolve_batch`)
+
+| Variable | Required | Description |
+|---|---|---|
+| `LOG10X_PASTE_URL` | No | Override the Log10x paste endpoint (default: `https://meljpepqpd.execute-api.us-east-1.amazonaws.com/paste`). Body limit 100 KB. |
+
+### Retriever (`log10x_retriever_query`, `log10x_backfill_metric`)
+
+| Variable | Required | Description |
+|---|---|---|
+| `__SAVE_LOG10X_RETRIEVER_URL__` | Yes (Retriever tier) | Base URL of the customer's deployed Retriever query endpoint (e.g., `https://retriever.<your-domain>`). When unset, Retriever-dependent tools return a graceful "not configured" message. |
+| `LOG10X_RETRIEVER_AUTH_HEADER` | No | Override the auth header name (default: `X-10X-Auth`, same as the Prometheus gateway). |
+| `LOG10X_RETRIEVER_AUTH_VALUE` | No | Override the auth header value. Default is `${apiKey}/${envId}` from the active environment. |
+| `__SAVE_LOG10X_RETRIEVER_TARGET__` | No | Override the default target prefix under which retriever writes indexed objects (default: `app`). |
+| `LOG10X_RETRIEVER_INDEX_SUBPATH` | No | Override the index subpath inside the bucket (default: `indexing-results`, matching the engine's indexContainer convention). |
+| `LOG10X_RETRIEVER_POLL_MS` | No | Override the marker-stability poll interval (default: `1500` ms). |
+| `LOG10X_RETRIEVER_TIMEOUT_MS` | No | Override the query timeout (default: `90000` ms). |
+
+**Demo env retriever LB**: the otel-demo cluster has a pre-provisioned retriever LoadBalancer at `http://a2936089108bb492cb41d18cb5b75f8d-1298006809.us-east-1.elb.amazonaws.com`. Set `__SAVE_LOG10X_RETRIEVER_URL__` to that value for the demo. The demo bucket is `tenx-demo-cloud-retriever-351939435334/indexing-results/`.
+
+**Known engine-side issues (GAPS G12)**: `log10x_retriever_query` has two unresolved engine-side bugs that `log10x_doctor` flags as `retriever_forensic_health` warnings: (1) it may return 0 events on windows where `log10x_pattern_trend` proves events exist, (2) it may crash with `MCP error -32000: Connection closed` when passed a canonical slash-underscore pattern name. Workarounds: use short/free-text pattern names, cross-check any zero result against `log10x_pattern_trend`, prefer `log10x_event_lookup` + `log10x_pattern_trend` for incident reconstruction where approximate timing is acceptable. See `docs/ENGINE_TICKETS.md` for the full engine-team ticket.
+
+### Metric backfill destinations (`log10x_backfill_metric`)
+
+| Variable | Required | Description |
+|---|---|---|
+| `DATADOG_API_KEY` (or `DD_API_KEY`) | Yes (Datadog destination) | Datadog API key used to POST to `/api/v2/series`. |
+| `DATADOG_SITE` | No | Datadog site (default: `datadoghq.com`, override for `datadoghq.eu`, `us5.datadoghq.com`, etc.) |
+| `PROMETHEUS_REMOTE_WRITE_URL` | Yes (Prometheus destination) | URL of a Prometheus `remote_write`-compatible adapter. The MCP posts JSON; the adapter translates to the native protobuf/Snappy wire format. |
+
 The server fetches your analyzer cost ($/GB) from your Console profile at startup and refreshes it hourly. To change it, update the cost in your profile — the server picks up the new value within an hour.
 
+## Spawning sub-agents that use this MCP
+
+If you script Claude Code sub-agents (`Agent` tool, OpenAI Agents SDK, custom orchestrators) to call log10x MCP tools, watch out for **deferred-tool bootstrapping**. The sub-agent's static tool list does not always include `mcp__log10x__*` — those tools are loaded on demand via `ToolSearch` (or the equivalent in your client). A sub-agent that reads its tool list and concludes "no MCP tools available" without first calling `ToolSearch({query: "log10x"})` will refuse the task instead of using the tools.
+
+In testing across 17 sub-agent runs, **prompt framing was the deciding factor**:
+
+| Framing | Bootstrap success |
+|---|---|
+| Action-oriented ("pull the events", "build the slide", "investigate this") | 9/9 |
+| Honesty-oriented ("don't fabricate", "refuse if you can't verify") | 0/5 |
+
+The honesty disposition fires too early — the agent applies "be honest about my limits" before trying to discover deferred tools. The fix is one line at the top of every sub-agent prompt:
+
+```
+TOOL BOOTSTRAP: You have log10x MCP tools available, but they are
+deferred-loaded. Before doing anything else, call
+ToolSearch({query: "log10x", max_results: 20}) to load them.
+After that you'll have mcp__log10x__log10x_* tools.
+```
+
+This raised bootstrap success from ~76% to 100% in our test runs and is harmless when MCP tools are already in scope.
+
+## Development
+
+Build:
+
+```bash
+npm install
+npm run build   # tsc → build/index.js
+```
+
+**Operational gotcha — restart after rebuild.** MCP clients (Claude Desktop, Claude Code, Cursor) typically launch the server as a long-running child process. Node caches loaded modules in memory, so the running process **will not pick up your `npm run build` output until it is killed and respawned**. After rebuilding, find and kill the stale processes:
+
+```bash
+pgrep -fl "log10x-mcp/build/index.js"   # show running servers + start times
+ps -o pid=,lstart= -p $(pgrep -f log10x-mcp/build/index.js)
+pkill -f "log10x-mcp/build/index.js"    # client will respawn on next tool call
+```
+
+If you ship a tool description change or a routing-hint update and the agent's behavior doesn't seem to reflect it, this is the most likely cause. Verify by `grep`-ing the raw tool output (most clients log it) for any string you added — if it's missing, the server is stale.
+
 ## Security
 
 - All API calls use your personal API key (never exposed in tool output)
@@ -145,4 +318,24 @@ Full documentation: [doc.log10x.com/manage/mcp-server](https://doc.log10x.com/ma
 
 ## License
 
-MIT
+This package is licensed under the [Apache License 2.0](LICENSE).
+
+### Important: Log10x Product License Required
+
+This package is the open-source MCP server for Log10x. While the MCP itself is open source,
+**using Log10x requires a commercial license**.
+
+| Component | License |
+|-----------|---------|
+| This package (`log10x-mcp`) | Apache 2.0 (open source) |
+| Log10x engine and runtime | Commercial license required |
+
+**What this means:**
+- You can freely use, modify, and distribute this MCP server
+- The Log10x backend services and `tenx` runtime that this MCP talks to require a paid subscription
+- A valid Log10x API key is required to call the account-scoped tools (sign in via `log10x_signin` or set `LOG10X_API_KEY`)
+
+**Get Started:**
+- [Log10x Pricing](https://log10x.com/pricing)
+- [Documentation](https://doc.log10x.com)
+- [Contact Sales](mailto:sales@log10x.com)