Telemetry and metrics

Virtual MCP Server (vMCP) provides comprehensive observability through OpenTelemetry instrumentation. You can export traces and metrics to monitor backend operations and workflow executions.

Telemetry types

vMCP supports two types of telemetry:

• Traces: Track requests across vMCP and its backends, showing the full path of tool calls, resource reads, and workflow executions
• Metrics: Counters and histograms for backend request rates, error rates, and latency distributions

For general ToolHive observability concepts including trace structure and metrics, see the observability overview.

Enable telemetry

Configure telemetry in the VirtualMCPServer resource using the spec.config.telemetry field:

apiVersion: toolhive.stacklok.dev/v1alpha1
kind: VirtualMCPServer
metadata:
  name: my-vmcp
  namespace: toolhive-system
spec:
  config:
    groupRef: my-group
    telemetry:
      endpoint: 'otel-collector:4318'
      serviceName: 'my-vmcp'
      insecure: true
      tracingEnabled: true
      samplingRate: '0.1'
      metricsEnabled: true
      enablePrometheusMetricsPath: true
  incomingAuth:
    type: anonymous

Configuration options

Field	Description	Default
endpoint	OTLP collector endpoint (hostname:port)	-
serviceName	Service name in traces and metrics	VirtualMCPServer name
tracingEnabled	Enable tracing	false
metricsEnabled	Enable OTLP metrics export	false
samplingRate	Trace sampling rate (0.0-1.0)	"0.05"
insecure	Use HTTP instead of HTTPS	false
enablePrometheusMetricsPath	Expose /metrics endpoint	false

Export to observability backends

Export to Jaeger via OpenTelemetry Collector

Deploy an OpenTelemetry Collector configured to export to Jaeger:

otel-collector-config.yaml

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:
    timeout: 10s
    send_batch_size: 1024

exporters:
  otlp/jaeger:
    endpoint: jaeger:4317
    tls:
      insecure: true

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/jaeger]

Then configure vMCP to send telemetry to the collector:

spec:
  config:
    telemetry:
      endpoint: 'otel-collector:4318'
      serviceName: 'production-vmcp'
      tracingEnabled: true
      metricsEnabled: true
      insecure: true

Metrics collection

vMCP supports two methods for collecting metrics:

• Push via OpenTelemetry: Set metricsEnabled: true to push metrics to your OTel Collector via OTLP
• Pull via Prometheus: Set enablePrometheusMetricsPath: true to expose a /metrics endpoint on the vMCP service port (4483) for Prometheus to scrape

Related information

• Observability concepts - Overview of ToolHive's observability architecture
• Kubernetes telemetry guide - Telemetry for MCPServer resources
• OpenTelemetry tutorial - Set up a local observability stack