feat: MCP integration for AI tools (#1091)

- Auto-create Grafana service account and token at startup
- Generate /etc/lgtm/mcp.json (mcp-grafana + Tempo native MCP)
- Generate /etc/lgtm/claude-mcp-setup.sh for one-command Claude Code setup
- Add opt-in collector debug exporter (OTEL_COLLECTOR_DEBUG_EXPORTER=true)
- Enable Tempo MCP server, expose port 3200
- Add docs/mcp-integration.md

Author: zeitlinger

README.md

@@ -304,6 +304,17 @@ OIDC_ISSUER="https://token.actions.githubusercontent.com"
 cosign verify ${IMAGE} --certificate-identity ${IDENTITY} --certificate-oidc-issuer ${OIDC_ISSUER}
 ```
 
+## AI Tool Integration (MCP)
+
+The container exposes [MCP servers][mcp] so AI coding tools can query traces, metrics, logs,
+and dashboards directly.
+
+```sh
+docker exec lgtm cat /etc/lgtm/mcp.json   # or: podman exec ...
+```
+
+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]
@@ -330,4 +341,5 @@ cosign verify ${IMAGE} --certificate-identity ${IDENTITY} --certificate-oidc-iss
 [otlp-endpoint]: https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_endpoint
 [otlp-headers]: https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_headers
 [oats]: https://github.com/grafana/oats
+[mcp]: https://modelcontextprotocol.io/ "Model Context Protocol"
 [red-method]: https://grafana.com/blog/the-red-method-how-to-instrument-your-services/ "The RED Method"

docker/otelcol-config-debug.yaml

@@ -0,0 +1,8 @@
+service:
+  pipelines:
+    traces:
+      exporters: [otlphttp/traces, debug/traces]
+    metrics:
+      exporters: [otlphttp/metrics, debug/metrics]
+    logs:
+      exporters: [otlphttp/logs, debug/logs]

docker/run-all.sh

@@ -131,6 +131,59 @@ 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
+# Try to create SA; if it already exists (persisted data), look it up
+SA_RESPONSE=$(curl -sf http://127.0.0.1:3000/api/serviceaccounts -H "Content-Type: application/json" -u admin:admin -d '{"name":"ai-tools","role":"Viewer"}')
+if [ -z "$SA_RESPONSE" ]; then
+	# SA already exists — find its ID
+	SA_RESPONSE=$(curl -sf "http://127.0.0.1:3000/api/serviceaccounts/search?query=ai-tools" -u admin:admin)
+	SA_ID=$(echo "$SA_RESPONSE" | grep -o '"id":[0-9]*' | head -1 | cut -d: -f2)
+else
+	SA_ID=$(echo "$SA_RESPONSE" | grep -o '"id":[0-9]*' | head -1 | cut -d: -f2)
+fi
+if [ -n "$SA_ID" ]; then
+	# Delete existing tokens and create a fresh one
+	EXISTING_TOKENS=$(curl -sf "http://127.0.0.1:3000/api/serviceaccounts/${SA_ID}/tokens" -u admin:admin)
+	for TOKEN_ID in $(echo "$EXISTING_TOKENS" | grep -o '"id":[0-9]*' | cut -d: -f2); do
+		curl -sf -X DELETE "http://127.0.0.1:3000/api/serviceaccounts/${SA_ID}/tokens/${TOKEN_ID}" -u admin:admin > /dev/null
+	done
+	TOKEN_RESPONSE=$(curl -sf "http://127.0.0.1:3000/api/serviceaccounts/${SA_ID}/tokens" -H "Content-Type: application/json" -u admin:admin -d '{"name":"ai-tools-token"}')
+	SA_TOKEN=$(echo "$TOKEN_RESPONSE" | grep -o '"key":"[^"]*"' | cut -d'"' -f4)
+	if [ -n "$SA_TOKEN" ]; then
+		echo "${SA_TOKEN}" > /tmp/grafana-sa-token
+		mkdir -p /etc/lgtm
+		EXEC="${CONTAINER_RUNTIME:-docker} exec lgtm"
+		cat > /etc/lgtm/mcp.json <<-MCPEOF
+		{
+		  "mcpServers": {
+		    "grafana": {
+		      "command": "uvx",
+		      "args": ["mcp-grafana"],
+		      "env": {
+		        "GRAFANA_URL": "http://localhost:3000",
+		        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "${SA_TOKEN}"
+		      }
+		    },
+		    "tempo": {
+		      "url": "http://localhost:3200/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=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=${SA_TOKEN} -- uvx mcp-grafana
+		claude mcp add --transport http tempo http://localhost:3200/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"
+		echo "  Docs:         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
@@ -153,6 +206,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.sh

@@ -78,5 +78,11 @@ if [[ -n ${OTEL_EXPORTER_OTLP_ENDPOINT:-} ||
 	fi
 fi
 
+debug_config_file=""
+if [[ ${OTEL_COLLECTOR_DEBUG_EXPORTER:-false} == "true" ]]; then
+	echo "Enabling debug exporter for OpenTelemetry Collector"
+	debug_config_file="--config=file:./otelcol-config-debug.yaml"
+fi
+
 run_with_logging "OpenTelemetry Collector ${OPENTELEMETRY_COLLECTOR_VERSION}" "${ENABLE_LOGS_OTELCOL:-false}" \
-	./otelcol-contrib/otelcol-contrib --feature-gates service.profilesSupport --config=file:./otelcol-config.yaml ${secondary_config_file}
+	./otelcol-contrib/otelcol-contrib --feature-gates service.profilesSupport --config=file:./otelcol-config.yaml ${secondary_config_file} ${debug_config_file}

docker/tempo-config.yaml

@@ -27,6 +27,10 @@ memberlist:
   bind_addr: [127.0.0.1]
   bind_port: 7947
 
+query_frontend:
+  mcp_server:
+    enabled: true
+
 querier:
   frontend_worker:
     frontend_address: 127.0.0.1:9096

docs/mcp-integration.md

@@ -0,0 +1,88 @@
+# AI Tool Integration (MCP)
+
+The `grafana/otel-lgtm` image exposes [Model Context Protocol (MCP)][mcp] servers
+so AI coding tools (Claude, Cursor, etc.) can query your telemetry data directly.
+
+## What you get
+
+- **Traces**: query via TraceQL through Tempo's built-in MCP server
+- **Metrics**: query via PromQL through Grafana MCP
+- **Logs**: query via LogQL through Grafana MCP
+- **Dashboards**: list, read, and search dashboards through Grafana MCP
+
+## Setup
+
+1. Start the container:
+
+   ```sh
+   ./run-lgtm.sh
+   ```
+
+2. Get the MCP config:
+
+   ```sh
+   docker exec lgtm cat /etc/lgtm/mcp.json   # or: podman exec ...
+   ```
+
+3. Paste the JSON into your AI tool's MCP configuration.
+
+   For Claude Code, you can add the servers individually:
+
+   ```sh
+   # Get the service account token
+   TOKEN=$(docker exec lgtm cat /tmp/grafana-sa-token)
+
+   # Add the Grafana MCP server (requires uvx)
+   claude mcp add grafana \
+     -e GRAFANA_URL=http://localhost:3000 \
+     -e GRAFANA_SERVICE_ACCOUNT_TOKEN="$TOKEN" \
+     -- uvx mcp-grafana
+
+   # Add the Tempo MCP server
+   claude mcp add --transport http tempo http://localhost:3200/api/mcp
+   ```
+
+## Backend mapping
+
+| Component  | MCP Server    | Transport | What you can query                  |
+|------------|---------------|-----------|-------------------------------------|
+| Tempo      | `tempo`       | HTTP      | Traces via TraceQL                  |
+| Grafana    | `grafana`     | stdio     | Dashboards, PromQL, LogQL           |
+
+## Collector debug exporter
+
+The OpenTelemetry Collector includes a debug exporter that logs all received
+telemetry to stdout. This is useful for verifying that data is flowing correctly.
+
+Enable it by setting the environment variable before starting the container:
+
+```sh
+OTEL_COLLECTOR_DEBUG_EXPORTER=true ./run-lgtm.sh
+```
+
+This adds the `debug` exporter to the traces, metrics, and logs pipelines.
+The output appears in the collector's logs (enable with `ENABLE_LOGS_OTELCOL=true`
+or `ENABLE_LOGS_ALL=true`).
+
+## OBI (eBPF auto-instrumentation)
+
+When [OBI is enabled][obi-readme], it generates traces and RED metrics automatically.
+These are queryable via PromQL through the Grafana MCP server:
+
+```promql
+# Number of instrumented processes
+obi_instrumented_processes
+
+# HTTP request duration (RED metrics)
+http_server_request_duration_seconds_count{http_route="/rolldice"}
+```
+
+See the [OBI section in README.md][obi-readme] for setup instructions.
+
+## Pyroscope (continuous profiling)
+
+Pyroscope collects continuous profiles on port 4040. Explore them in Grafana's
+**Explore > Profiles** view. There is no MCP integration for Pyroscope yet.
+
+[mcp]: https://modelcontextprotocol.io/
+[obi-readme]: ../README.md#enable-obi-ebpf-auto-instrumentation

examples/python/oats.yaml

@@ -13,6 +13,8 @@ expected:
   # We also check that this exact log line is present in the logs, which some users rely on
   compose-logs:
     - "The OpenTelemetry collector and the Grafana LGTM stack are up and running. (created /tmp/ready)"
+    - "AI Tool Integration (MCP):"
+    - "docker exec lgtm cat /etc/lgtm/mcp.json"
   traces:
     - traceql: '{ span.http.route = "/rolldice" }'
       equals: "GET /rolldice"

run-lgtm.sh

@@ -64,6 +64,7 @@ $RUNTIME container run \
 	"${OBI_FLAGS[@]}" \
 	"${OBI_ENV_FLAGS[@]}" \
 	-p 3000:3000 \
+	-p 3200:3200 \
 	-p 4040:4040 \
 	-p 4317:4317 \
 	-p 4318:4318 \
@@ -74,5 +75,6 @@ $RUNTIME container run \
 	-v "${LOCAL_VOLUME}"/prometheus:/data/prometheus:"${MOUNT_OPTS}" \
 	-v "${LOCAL_VOLUME}"/loki:/data/loki:"${MOUNT_OPTS}" \
 	-e GF_PATHS_DATA=/data/grafana \
+	-e CONTAINER_RUNTIME="$RUNTIME" \
 	--env-file .env \
 	"$IMAGE"