feat: MCP integration for AI tools

.github/renovate-tracked-deps.json

@@ -276,6 +276,7 @@
   },
   "mise.toml": {
     "mise": [
+      "bats",
       "go",
       "go:github.com/grafana/oats",
       "java",

.github/workflows/lint.yml

@@ -26,8 +26,8 @@ jobs:
           version: v2026.3.16
           sha256: 1aadc8f126b0fc588b70ad2296cf7a963ba014ef2fd017a6087329ec6160063e
 
-      - name: Lint
+      - name: CI checks
         env:
           GITHUB_TOKEN: ${{ github.token }}
           GITHUB_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
-        run: mise run lint
+        run: mise run ci

AGENTS.md

@@ -49,11 +49,17 @@ mise run fix
 
 # Verify only (same command used in CI)
 mise run lint
+
+# Run without Docker/Podman (e.g. inside a container)
+NATIVE=true mise run lint:fast
 ```
 
 After running `fix`, always review the changed files before committing —
 auto-fixes may produce unexpected results.
 
+Native mode requires lint tools on PATH. Run `mise run setup:native-lint-tools`
+once to install them.
+
 Go code uses `.golangci.yaml` config. Markdown uses `.markdownlint.yaml`.
 EditorConfig rules in `.editorconfig`.
 
@@ -77,6 +83,7 @@ for other components. Each component has a `run-*.sh` startup script.
 ### Example Applications (examples/)
 
 Language-specific demo apps that emit OpenTelemetry data:
+
 - `examples/java` (port 8080) - Maven + OTel Java Agent
 - `examples/go` (port 8081) - Go workspace (`go.work` at repository root)
 - `examples/python` (port 8082) - Python + auto-instrumentation

README.md

@@ -139,9 +139,9 @@ to the specified endpoint using "OTLP/HTTP".
 
 You can also configure per-signal endpoints:
 
-* `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`
-* `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`
-* `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`
+- `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`
+- `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`
+- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`
 
 If both global and per-signal endpoints are set, per-signal values take precedence.
 Endpoints must include the scheme (for example, `http://jaeger:4318`).
@@ -257,7 +257,7 @@ services:
 kubectl apply -f k8s/lgtm.yaml
 
 # Configure port forwarding
-kubectl port-forward service/lgtm 3000:3000 4040:4040 4317:4317 4318:4318 9090:9090
+kubectl port-forward service/lgtm 3000:3000 3200:3200 4040:4040 4317:4317 4318:4318 9090:9090
 
 # Using mise
 mise k8s-apply
@@ -387,6 +387,19 @@ OIDC_ISSUER="https://token.actions.githubusercontent.com"
 cosign verify ${IMAGE} --certificate-identity ${IDENTITY} --certificate-oidc-issuer ${OIDC_ISSUER}
 ```
 
+## AI Tool Integration (MCP)
+
+The stack provides an [MCP][mcp] integration so AI coding tools can query logs, metrics, traces,
+and dashboards. Tempo exposes an HTTP MCP endpoint from the container, while Grafana
+dashboards and queries are accessed via a client-side MCP server (`uvx mcp-grafana`).
+
+```sh
+docker exec lgtm cat /etc/lgtm/mcp.json   # or: podman exec ...
+# Kubernetes: kubectl exec deploy/lgtm -- cat /etc/lgtm/mcp.json
+```
+
+Paste the JSON into your AI tool's MCP configuration. See [docs/mcp-integration.md](docs/mcp-integration.md) for details.
+
 ## Related Work
 
 - [Metrics, Logs, Traces and Profiles in Grafana][mltp]
@@ -406,6 +419,7 @@ cosign verify ${IMAGE} --certificate-identity ${IDENTITY} --certificate-oidc-iss
 [grafana-env-overrides]: https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/#override-configuration-with-environment-variables
 [grafana-preinstall-plugins]: https://grafana.com/docs/grafana/latest/setup-grafana/configure-docker/#install-plugins-in-the-docker-container
 [java-example]: examples/java/
+[mcp]: https://modelcontextprotocol.io/ "Model Context Protocol"
 [mise]: https://github.com/jdx/mise
 [mltp]: https://github.com/grafana/intro-to-mltp
 [otel-checker]: https://github.com/grafana/otel-checker/

docker/run-all.sh

@@ -142,6 +142,78 @@ echo "Total: ${total_elapsed} seconds"
 touch /tmp/ready
 echo "The OpenTelemetry collector and the Grafana LGTM stack are up and running. (created /tmp/ready)"
 
+# Create a service account token and MCP config for AI tool access
+GRAFANA_CREDS="${GF_SECURITY_ADMIN_USER:-admin}:${GF_SECURITY_ADMIN_PASSWORD:-admin}"
+GRAFANA_URL="${GRAFANA_URL:-http://127.0.0.1:3000}"
+GRAFANA_PUBLIC_URL="${GRAFANA_PUBLIC_URL:-http://localhost:3000}"
+TEMPO_URL="${TEMPO_URL:-http://localhost:3200}"
+SA_NAME="ai-tools"
+SA_TOKEN_NAME="ai-tools-token"
+GRAFANA_SA_URL="${GRAFANA_URL}/api/serviceaccounts"
+# Try to create SA; if it already exists (persisted data), look it up
+SA_RESPONSE="$(curl -sf "${GRAFANA_SA_URL}" \
+	-H "Content-Type: application/json" -u "${GRAFANA_CREDS}" \
+	-d "{\"name\":\"${SA_NAME}\",\"role\":\"Viewer\"}")"
+if [ -z "$SA_RESPONSE" ]; then
+	# SA already exists — find its ID
+	SA_RESPONSE="$(curl -sf "${GRAFANA_SA_URL}/search?query=${SA_NAME}" -u "${GRAFANA_CREDS}")"
+fi
+SA_ID="$(echo "$SA_RESPONSE" | grep -o '"id":[0-9]*' | head -1 | cut -d: -f2)"
+if [ -n "$SA_ID" ]; then
+	# Delete only the bootstrap-managed token (preserve any manually-created tokens)
+	EXISTING_TOKENS="$(curl -sf "${GRAFANA_SA_URL}/${SA_ID}/tokens" -u "${GRAFANA_CREDS}")"
+	if [ -n "$EXISTING_TOKENS" ]; then
+		BOOTSTRAP_TOKEN_ID="$(echo "$EXISTING_TOKENS" | tr '{}' '\n' |
+			grep "\"name\":\"${SA_TOKEN_NAME}\"" | grep -o '"id":[0-9]*' | head -1 | cut -d: -f2)"
+		if [ -n "$BOOTSTRAP_TOKEN_ID" ]; then
+			curl -sf -X DELETE "${GRAFANA_SA_URL}/${SA_ID}/tokens/${BOOTSTRAP_TOKEN_ID}" \
+				-u "${GRAFANA_CREDS}" >/dev/null
+		fi
+	fi
+	TOKEN_RESPONSE="$(curl -sf "${GRAFANA_SA_URL}/${SA_ID}/tokens" \
+		-H "Content-Type: application/json" -u "${GRAFANA_CREDS}" \
+		-d "{\"name\":\"${SA_TOKEN_NAME}\"}")"
+	SA_TOKEN="$(echo "$TOKEN_RESPONSE" | grep -o '"key":"[^"]*"' | cut -d'"' -f4)"
+	if [ -n "$SA_TOKEN" ]; then
+		EXEC="${CONTAINER_RUNTIME:-docker} exec lgtm"
+		(
+			umask 077
+			mkdir -p /etc/lgtm
+			echo "${SA_TOKEN}" >/tmp/grafana-sa-token
+			cat >/etc/lgtm/mcp.json <<-MCPEOF
+				{
+				  "mcpServers": {
+				    "grafana": {
+				      "command": "uvx",
+				      "args": ["mcp-grafana"],
+				      "env": {
+				        "GRAFANA_URL": "${GRAFANA_PUBLIC_URL}",
+				        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "${SA_TOKEN}"
+				      }
+				    },
+				    "tempo": {
+				      "url": "${TEMPO_URL}/api/mcp"
+				    }
+				  }
+				}
+			MCPEOF
+			cat >/etc/lgtm/claude-mcp-setup.sh <<-SETUPEOF
+				#!/bin/bash
+				# Connect Claude Code to the LGTM stack
+				claude mcp add grafana -e "GRAFANA_URL=${GRAFANA_PUBLIC_URL}" -e "GRAFANA_SERVICE_ACCOUNT_TOKEN=${SA_TOKEN}" -- uvx mcp-grafana
+				claude mcp add --transport http tempo "${TEMPO_URL}/api/mcp"
+			SETUPEOF
+		)
+		echo ""
+		echo "AI Tool Integration (MCP):"
+		echo "  Claude Code:  bash <($EXEC cat /etc/lgtm/claude-mcp-setup.sh)"
+		echo "  Other tools:  $EXEC cat /etc/lgtm/mcp.json"
+		docs_ref="main"
+		[[ -n "${LGTM_VERSION}" ]] && docs_ref="v${LGTM_VERSION}"
+		echo "  Docs:         https://github.com/grafana/docker-otel-lgtm/blob/${docs_ref}/docs/mcp-integration.md"
+	fi
+fi
+
 if [[ ${ENABLE_OBI:-false} == "true" ]]; then
 	# Non-blocking check — don't delay readiness if OBI fails (e.g. missing capabilities)
 	if curl -o /dev/null -sg "http://127.0.0.1:6060/metrics" -w "%{response_code}" 2>/dev/null | grep -q "200"; then
@@ -164,6 +236,7 @@ echo "Open ports:"
 echo " - 4317: OpenTelemetry GRPC endpoint"
 echo " - 4318: OpenTelemetry HTTP endpoint"
 echo " - 3000: Grafana (http://localhost:3000). User: admin, password: admin"
+echo " - 3200: Tempo endpoint (MCP at http://localhost:3200/api/mcp)"
 echo " - 4040: Pyroscope endpoint"
 echo " - 9090: Prometheus endpoint"
 

docker/run-otelcol.bats

@@ -0,0 +1,146 @@
+#!/usr/bin/env bats
+# shellcheck disable=SC2030,SC2031  # export in @bats test is intentionally local
+bats_require_minimum_version 1.5.0
+# Tests for run-otelcol.sh config generation logic.
+# The script is run in a temp dir with a stub logging.sh so that
+# run_with_logging records its args without exec-ing the real binary.
+
+setup() {
+	TESTDIR=$(mktemp -d)
+
+	# Stub logging.sh: record otelcol args to a file instead of exec-ing.
+	cat >"$TESTDIR/logging.sh" <<EOF
+run_with_logging() {
+	shift 2  # skip name and envvar args
+	printf '%s\n' "\$@" >"$TESTDIR/otelcol-invocation"
+}
+EOF
+
+	cp "$BATS_TEST_DIRNAME/run-otelcol.sh" "$TESTDIR/"
+
+	export OPENTELEMETRY_COLLECTOR_VERSION="test"
+	unset OTEL_EXPORTER_OTLP_ENDPOINT \
+		OTEL_EXPORTER_OTLP_TRACES_ENDPOINT \
+		OTEL_EXPORTER_OTLP_METRICS_ENDPOINT \
+		OTEL_EXPORTER_OTLP_LOGS_ENDPOINT \
+		OTEL_EXPORTER_OTLP_HEADERS \
+		OTEL_COLLECTOR_DEBUG_EXPORTER \
+		OTELCOL_EXTRA_ARGS 2>/dev/null || true
+}
+
+teardown() {
+	rm -rf "$TESTDIR"
+}
+
+run_otelcol() {
+	cd "$TESTDIR" && bash run-otelcol.sh
+}
+
+# --- no flags ---
+
+@test "no flags: no overlay config generated" {
+	run run_otelcol
+	[ "$status" -eq 0 ]
+	[ ! -f "$TESTDIR/otelcol-config-export-http.yaml" ]
+}
+
+@test "no flags: otelcol started with only base config" {
+	run run_otelcol
+	[ "$status" -eq 0 ]
+	grep -q -- "--config=file:./otelcol-config.yaml" "$TESTDIR/otelcol-invocation"
+	run ! grep -q "otelcol-config-export-http" "$TESTDIR/otelcol-invocation"
+}
+
+# --- debug only ---
+
+@test "debug only: overlay generated" {
+	export OTEL_COLLECTOR_DEBUG_EXPORTER=true
+	run run_otelcol
+	[ "$status" -eq 0 ]
+	[ -f "$TESTDIR/otelcol-config-export-http.yaml" ]
+}
+
+@test "debug only: overlay has debug exporters for all signals" {
+	export OTEL_COLLECTOR_DEBUG_EXPORTER=true
+	run run_otelcol
+	grep -q "debug/traces" "$TESTDIR/otelcol-config-export-http.yaml"
+	grep -q "debug/metrics" "$TESTDIR/otelcol-config-export-http.yaml"
+	grep -q "debug/logs" "$TESTDIR/otelcol-config-export-http.yaml"
+}
+
+@test "debug only: overlay has no external exporters" {
+	export OTEL_COLLECTOR_DEBUG_EXPORTER=true
+	run run_otelcol
+	run ! grep -q "otlphttp/external" "$TESTDIR/otelcol-config-export-http.yaml"
+}
+
+@test "debug only: overlay passed to otelcol" {
+	export OTEL_COLLECTOR_DEBUG_EXPORTER=true
+	run run_otelcol
+	grep -q "otelcol-config-export-http" "$TESTDIR/otelcol-invocation"
+}
+
+# --- external only (shared endpoint) ---
+
+@test "external only: overlay has external exporters for all signals" {
+	export OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318
+	run run_otelcol
+	grep -q "otlphttp/external-traces" "$TESTDIR/otelcol-config-export-http.yaml"
+	grep -q "otlphttp/external-metrics" "$TESTDIR/otelcol-config-export-http.yaml"
+	grep -q "otlphttp/external-logs" "$TESTDIR/otelcol-config-export-http.yaml"
+}
+
+@test "external only: overlay has no debug exporters" {
+	export OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318
+	run run_otelcol
+	run ! grep -q "debug/" "$TESTDIR/otelcol-config-export-http.yaml"
+}
+
+# --- per-signal external endpoints ---
+
+@test "per-signal: only configured signals get external exporter" {
+	export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://tempo:4318
+	run run_otelcol
+	grep -q "otlphttp/external-traces" "$TESTDIR/otelcol-config-export-http.yaml"
+	run ! grep -q "otlphttp/external-metrics" "$TESTDIR/otelcol-config-export-http.yaml"
+	run ! grep -q "otlphttp/external-logs" "$TESTDIR/otelcol-config-export-http.yaml"
+}
+
+# --- both debug and external ---
+
+@test "both: overlay has debug and external exporters for all signals" {
+	export OTEL_COLLECTOR_DEBUG_EXPORTER=true
+	export OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318
+	run run_otelcol
+	grep -q "debug/traces" "$TESTDIR/otelcol-config-export-http.yaml"
+	grep -q "debug/metrics" "$TESTDIR/otelcol-config-export-http.yaml"
+	grep -q "debug/logs" "$TESTDIR/otelcol-config-export-http.yaml"
+	grep -q "otlphttp/external-traces" "$TESTDIR/otelcol-config-export-http.yaml"
+	grep -q "otlphttp/external-metrics" "$TESTDIR/otelcol-config-export-http.yaml"
+	grep -q "otlphttp/external-logs" "$TESTDIR/otelcol-config-export-http.yaml"
+}
+
+@test "both: only one overlay config passed to otelcol" {
+	export OTEL_COLLECTOR_DEBUG_EXPORTER=true
+	export OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318
+	run run_otelcol
+	count=$(grep -c "otelcol-config-export-http" "$TESTDIR/otelcol-invocation")
+	[ "$count" -eq 1 ]
+}
+
+# --- headers ---
+
+@test "headers: added to external endpoints in overlay" {
+	export OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318
+	export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer token123"
+	run run_otelcol
+	grep -q "headers:" "$TESTDIR/otelcol-config-export-http.yaml"
+	grep -q "Authorization" "$TESTDIR/otelcol-config-export-http.yaml"
+}
+
+@test "headers: not applied when debug only (no external endpoints)" {
+	export OTEL_COLLECTOR_DEBUG_EXPORTER=true
+	export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer token123"
+	run run_otelcol
+	run ! grep -q "headers:" "$TESTDIR/otelcol-config-export-http.yaml"
+}