Skip to main content

OpenTelemetry MCP Server Tools Reference

The TalkOps OpenTelemetry MCP Server exposes 19 specialized tools organized across 7 functional areas. Every mutating tool defaults to dry_run=True to ensure you can inspect generated YAML diffs before applying changes to your live Kubernetes clusters.

1. Discovery Tools​

otel_list_collectors​

List OpenTelemetryCollector custom resources across namespaces with label filtering and cursor-based pagination.

Parameters:

ParameterTypeRequiredDescription
namespacestringNoTarget namespace. Omit to search all namespaces across the cluster.
label_selectorstringNoStandard Kubernetes label selector (e.g. app=monitoring,env=prod).
limitintegerNoMaximum collectors to return per page (default: 20).
cursorstringNoOpaque pagination cursor token from a previous call.

Example Invocation:

{
  "namespace": "monitoring",
  "label_selector": "app.kubernetes.io/part-of=opentelemetry"
}

otel_get_collector​

Retrieve complete metadata, pipeline topology (receivers, processors, exporters, connectors), and raw YAML specifications for a specific collector.

Parameters:

ParameterTypeRequiredDescription
namestringYesName of the OpenTelemetryCollector resource.
namespacestringYesTarget namespace where the collector is deployed.
include_raw_configbooleanNoInclude raw string YAML representation in the output (default: true).

otel_query_a2ui​

Fetch real-time pipeline status and operational health metrics across all deployed collectors, formatted specifically for A2UI status tables.

Parameters:

ParameterTypeRequiredDescription
namespacestringNoScopes the health query to a specific namespace. Omit for cluster-wide status.

otel_list_instrumented_services​

Inspect all workloads in a namespace to determine their OpenTelemetry auto-instrumentation injection status, annotation keys, init container presence, and detected programming language using 4-tier detection.

Parameters:

ParameterTypeRequiredDescription
namespacestringYesTarget namespace to inspect (e.g. production).

2. Collector Management Tools​

otel_provision_collector​

Intent-Driven Provisioning: Express desired signals and a namespace — the server automatically discovers active backends (Tempo, Mimir, Jaeger, Prometheus), generates best-practice configurations with validated processor chains, creates the necessary ClusterRole and ClusterRoleBinding for k8sattributes, and scales resources to your cluster size.

Parameters:

ParameterTypeRequiredDescription
namespacestringYesTarget namespace for the collector deployment.
signalsarray[string]YesArray of desired signals: ["traces", "metrics", "logs"].
enable_spanmetricsbooleanNoWire up a spanmetrics connector from traces to metrics (default: false).
enable_filelogbooleanNoConfigure a filelog receiver with checkpoint storage (default: false).
prometheus_scrapebooleanNoEnable Prometheus scraping via Target Allocator (default: false).
dry_runbooleanNoValidate and output YAML without applying to cluster (default: true).

Example Invocation:

{
  "namespace": "payments",
  "signals": ["traces", "metrics"],
  "enable_spanmetrics": true,
  "dry_run": false
}

otel_patch_collector​

Expert-level CRD creation and patching. Allows direct replacement or surgical updates of an OpenTelemetryCollector resource with schema validation and resourceVersion concurrency control.

Parameters:

ParameterTypeRequiredDescription
namestringYesName of the collector resource.
namespacestringYesNamespace where the collector resides.
config_yamlstringYesValid OpenTelemetry collector configuration YAML.
modestringNoDeployment mode: Deployment, DaemonSet, or StatefulSet.
overwritebooleanNoOverwrite entire CRD instead of performing a 3-way strategic merge (default: false).
dry_runbooleanNoValidate syntax without applying (default: true).

3. Workload Auto-Instrumentation Tools​

otel_lookup_instrumentation​

Check auto-instrumentation capabilities, SDK packages, and required annotations for a given programming language and optional framework.

Parameters:

ParameterTypeRequiredDescription
languagestringYesTarget language (python, java, nodejs, golang, dotnet, rust).
frameworkstringNoSpecific framework (e.g. fastapi, spring-boot, express, gin).

otel_patch_instrumentation​

Create or update an Instrumentation CRD defining telemetry exporter endpoints, W3C trace context propagators, sampler ratios, and container image overrides.

Parameters:

ParameterTypeRequiredDescription
namestringYesName of the Instrumentation CRD (e.g. prod-instrumentation).
namespacestringYesTarget namespace for the CRD.
exporter_endpointstringYesOTLP collector receiver endpoint (e.g. http://otel-collector.monitoring:4317).
sampler_typestringNoSampler algorithm (parentbased_traceidratio, traceidratio, always_on, always_off).
sampler_argumentstringNoSampler ratio value (e.g. "0.10" for 10% sampling).
dry_runbooleanNoGenerate YAML preview without creating the CRD (default: true).

otel_annotate_deployment​

Apply auto-instrumentation injection annotations to a Deployment's pod template. Scans container environment variables for conflicting hardcoded OTEL_* settings before updating.

Parameters:

ParameterTypeRequiredDescription
deployment_namestringYesName of the target Deployment.
namespacestringYesTarget namespace.
languagestringYesRuntime language (java, python, nodejs, dotnet, go).
instrumentation_namestringNoName of the Instrumentation CRD to bind (defaults to default-instrumentation).
dry_runbooleanNoReview annotation diff before triggering a rolling restart (default: true).

4. Pipeline Validation Tools​

otel_validate_k8sattributes_order​

Validates processor execution order in collector pipelines against OpenTelemetry architecture standards (memory_limiter → k8sattributes → resourcedetection → transform → filter → tail_sampling → batch).

Parameters:

ParameterTypeRequiredDescription
collector_namestringYesName of the collector to audit.
namespacestringYesNamespace of the collector.

otel_check_filelog_safety​

Audits filelog receivers to ensure checkpoint storage (file_storage extension) is configured and verifies self-collection log exclusion patterns to avoid runaway logging feedback loops.

Parameters:

ParameterTypeRequiredDescription
collector_namestringYesName of the collector running the filelog receiver.
namespacestringYesNamespace of the collector.

otel_inspect_target_allocator_state​

Inspects Prometheus Target Allocator configuration, scraping strategies (consistent-hashing vs per-node), and ServiceMonitor/PodMonitor selector matches.

Parameters:

ParameterTypeRequiredDescription
collector_namestringYesName of the collector managing the Target Allocator.
namespacestringYesNamespace of the collector.

otel_recommend_collector_topology​

Evaluates cluster node count, expected event volume, and signal diversity to recommend the optimal collector architecture (DaemonSet, Deployment, or Multi-Tier Gateway).

Parameters:

ParameterTypeRequiredDescription
namespacestringYesTarget namespace for the planned deployment.
workload_countintegerNoApproximate number of application pods to monitor.
signalsarray[string]NoTelemetry signals to handle: ["traces", "metrics", "logs"].

5. Governance & Cardinality Tools​

otel_detect_cardinality​

Audits metric dimensions and histogram configurations in SpanMetrics connectors, highlighting dimensions likely to trigger time-series explosions.

Parameters:

ParameterTypeRequiredDescription
collector_namestringYesName of the collector running SpanMetrics.
namespacestringYesNamespace of the collector.
thresholdintegerNoCardinality warning threshold (default: 10000).

otel_gen_drop_attribute_rules​

Generates OpenTelemetry Transformation Language (OTTL) statements for a transform processor to strip high-cardinality or sensitive attributes before export.

Parameters:

ParameterTypeRequiredDescription
signalstringYesTarget signal: metrics, traces, or logs.
attributes_to_droparray[string]YesList of attribute keys to drop (e.g. ["http.url", "user.id"]).

otel_analyze_ebpf_footprint​

Scans cluster nodes and DaemonSets for eBPF observability agents (Grafana Beyla, OTel eBPF), verifying privileged access, host PID mode, and Linux capabilities.

Parameters:

ParameterTypeRequiredDescription
namespacestringNoScopes the audit to a namespace. Omit to audit the entire cluster.

6. Sampling Management Tools​

otel_inspect_sampling_configuration​

Cross-references SDK head sampling with collector tail sampling to detect conflicting configurations and unintended trace drop rules.

Parameters:

ParameterTypeRequiredDescription
collector_namestringYesName of the trace collector to evaluate.
namespacestringYesNamespace of the collector.

otel_toggle_sampling_strategy​

Generates configuration patches to switch between head sampling, tail sampling, or hybrid error-retention sampling.

Parameters:

ParameterTypeRequiredDescription
collector_namestringYesTarget collector name.
namespacestringYesTarget namespace.
strategystringYesSampling architecture: head, tail, or hybrid.
tail_sampling_percentagenumberNoBase percentage for non-error traces in hybrid mode (e.g. 10.0).
dry_runbooleanNoGenerate patch YAML without applying (default: true).

7. SpanMetrics Connector Tools​

otel_inspect_spanmetrics_config​

Audits existing SpanMetrics connector configuration, metric naming conventions, and dimension mappings.

Parameters:

ParameterTypeRequiredDescription
collector_namestringYesName of the collector with SpanMetrics enabled.
namespacestringYesNamespace of the collector.

otel_enable_spanmetrics_for_service​

Generates and injects a spanmetrics connector configuration into an OpenTelemetryCollector pipeline, configuring custom dimensions and latency histogram bucket boundaries.

Parameters:

ParameterTypeRequiredDescription
collector_namestringYesTarget collector name.
namespacestringYesTarget namespace.
dimensionsarray[string]NoExplicit span attributes to promote to metric labels.
histogram_bucketsarray[number]NoLatency bucket boundaries in seconds (e.g. [0.005, 0.01, 0.05, 0.1, 0.5, 1.0, 5.0]).
dry_runbooleanNoOutput YAML without applying (default: true).