AI-Assisted Observability

autotel-mcp is Autotel’s investigation server for Claude, Codex, Cursor, VS Code, Windsurf, and other MCP-compatible agents. It can receive all three OpenTelemetry signals itself or query an existing backend.

How it works

Your app ──OTLP──> collector or vendor backend
                         ▲
                         │ traces / metrics / logs
                    autotel-mcp
                         ▲
                         │ MCP
                      AI agent

The server exposes 41 tools for progressive investigation: discover the available services and fields, search traces or spans, inspect a complete trace, diagnose anomalies and root causes, correlate logs and metrics, and analyse GenAI usage.

Fastest setup: built-in collector

The default backend starts an OTLP/HTTP JSON receiver on port 4318 and stores telemetry in memory.

1. Point your app at the receiver

import { init } from 'autotel';

init({
  service: 'checkout',
  endpoint: 'http://127.0.0.1:4318',
  protocol: 'http', // OTLP/HTTP JSON; the built-in collector's wire format
});

Wrap handlers with trace() or the relevant framework middleware, then attach the context an investigation will need with span attributes or getRequestLogger().

2. Add the MCP server to your client

{
  "mcpServers": {
    "autotel": {
      "command": "npx",
      "args": ["autotel-mcp"]
    }
  }
}

For Claude Code:

claude mcp add autotel npx autotel-mcp

Restart the client after changing its MCP configuration. The server writes status messages to stderr so the stdio protocol on stdout stays valid.

3. Ask an investigation question

Good prompts give the agent a service, time range, and symptom:

“Why did checkout get slower in the last hour?”
“Find error traces for payments, then inspect the most recent complete trace.”
“Correlate logs and metrics for trace <trace-id>.”
“Which model used the most tokens today, and which traces drove that usage?”

The agent can call list_capabilities first, so it knows which signals and tools the selected backend can answer.

Query an existing backend

Set AUTOTEL_BACKEND and its connection variables in the MCP client’s env. Credentials must stay in environment variables, not command arguments.

{
  "mcpServers": {
    "autotel": {
      "command": "npx",
      "args": ["autotel-mcp"],
      "env": {
        "AUTOTEL_BACKEND": "jaeger",
        "JAEGER_BASE_URL": "http://localhost:16686"
      }
    }
  }
}

Backend	Connection variables	Signals read
`collector`	`AUTOTEL_COLLECTOR_PORT`	traces, metrics, logs
`devtools`	`DEVTOOLS_BASE_URL`	traces
`jaeger`	`JAEGER_BASE_URL`	traces
`tempo`	`TEMPO_BASE_URL`	traces
`prometheus`	`PROMETHEUS_BASE_URL`	metrics
`loki`	`LOKI_BASE_URL`	logs
`stack`	one or more of the Tempo/Jaeger, Prometheus, and Loki variables above	configured signals
`auto`	the self-hosted base URLs above	detected signals
`fixture`	`AUTOTEL_FIXTURE_PATH`	fixture contents
`logfire`	`LOGFIRE_BASE_URL`, `LOGFIRE_READ_TOKEN`	traces
`datadog`	`DD_SITE`, `DD_API_KEY`, `DD_APP_KEY`	traces
`signoz`	`SIGNOZ_BASE_URL`, optional `SIGNOZ_API_KEY`	traces

logfire, datadog, and signoz are deliberately trace-only. Their capability response says metrics and logs are unsupported, which is different from a supported query returning no data. Trace searches discover matching trace IDs and then hydrate every complete trace before diagnosis.

Hosted-backend details

Logfire querying needs a read-scope token and the regional query host. Its ingest write token has a different scope and authorization format.
Datadog querying needs both the organization API key and a personal application key. DD_SITE accepts a bare site such as uk1.datadoghq.com or a complete API URL.
SigNoz uses the Query Builder v5 API. SIGNOZ_API_KEY can be omitted for an unauthenticated self-hosted deployment.

Investigation workflow

The tools are grouped around a predictable loop:

backend_health, backend_capabilities, and list_capabilities establish what is reachable and supported.
discover_services, discover_trace_fields, and discover_log_fields establish the searchable vocabulary.
search_traces, search_spans, search_logs, and list_metrics narrow the evidence.
get_trace and summarize_trace retrieve the complete execution.
find_anomalies, find_errors, find_root_cause, correlate, and explain_slowdown turn the evidence into a diagnosis.

There are also dedicated GenAI analytics, semantic-convention discovery, instrumentation scoring, and OpenTelemetry Collector configuration tools. Use list_capabilities as the live tool manifest instead of hard-coding a list in an agent prompt.

GenAI investigations

Applications emit LLM telemetry through autotel-genai, not core autotel:

import { traceGenAI, recordGenAiUsage } from 'autotel-genai/trace';

const chat = traceGenAI({
  provider: 'openai',
  operation: 'chat',
  model: 'gpt-5',
})((ctx) => async () => {
  const response = await callModel();
  recordGenAiUsage(ctx, 'gpt-5', {
    inputTokens: response.usage.inputTokens,
    outputTokens: response.usage.outputTokens,
  });
  return response;
});

const answer = await chat();

The MCP server reads the canonical gen_ai.* attributes for model, token, latency, cost, and tool-use analysis. Before relying on those results, use scoreGenAiCompleteness() to catch traces that lost critical evidence.

Verify ingest freshness

Reachability alone does not prove that a newly written span is queryable. Test the complete write/read loop with the CLI:

npx autotel health \
  --backend jaeger \
  --otlp-endpoint http://localhost:4318

The result includes freshness.timeToQueryableSeconds. For hosted endpoints, provide the write credential through OTEL_EXPORTER_OTLP_HEADERS; backend read credentials remain in their vendor-specific environment variables. See the CLI reference.

Running beside autotel-devtools

Both the default MCP collector and autotel-devtools want port 4318. To give the browser UI and agent the same traces, let devtools own the receiver and query it from MCP:

npx autotel-devtools
AUTOTEL_BACKEND=devtools npx autotel-mcp

The devtools read API currently exposes traces only. Use the standalone MCP collector when the agent must query logs and metrics too.

MCP: complete server and instrumentation setup.
CLI: the same investigation model from shell commands.
AI / LLM Workflows: emit canonical GenAI telemetry.
Telemetry Schema: validate trace contracts and GenAI trace completeness.