Context

gh-aw#24602 was merged, extending the MCP Gateway Specification from v1.10.0 to v1.11.0. It adds an optional opentelemetry configuration object to the gateway config section. When configured, the gateway must emit distributed tracing spans for each MCP tool invocation using OTLP/HTTP.

Related: #3177 — our existing feature issue for OTLP tracing (architecture analysis + solution proposal). This issue focuses specifically on spec compliance with v1.11.0.

What the spec requires (§4.1.3.6)

Config schema (opentelemetry object in gateway)

Required tracing behavior

When opentelemetry is configured, the gateway MUST:

1. Create a root span for the gateway process lifetime with service.name set to serviceName
2. Create a child span per MCP tool invocation with attributes:
   • mcp.server — server name from config
   • mcp.method — JSON-RPC method (e.g., tools/call)
   • mcp.tool — tool name
   • http.status_code — HTTP status of proxied response
3. Record accurate start/end timestamps
4. Export via OTLP/HTTP to the configured endpoint
5. Apply configured headers to every export request
6. Propagate W3C traceparent when traceId/spanId provided

Failure handling

• Gateway MUST NOT fail to start if collector is unreachable
• Export failures SHOULD be logged as warnings, MUST NOT affect MCP processing
• SHOULD implement exponential backoff retry

Validation rules

• endpoint required when opentelemetry present
• endpoint MUST be HTTPS
• traceId must be 32-char lowercase hex (or ${VAR})
• spanId must be 16-char lowercase hex (or ${VAR})
• spanId without traceId → log warning, ignore

Gap analysis: current gateway vs spec

Existing TracingConfig (from recent work)

type TracingConfig struct {
    Endpoint    string   `toml:"endpoint" json:"endpoint,omitempty"`
    ServiceName string   `toml:"service_name" json:"service_name,omitempty"`
    SampleRate  *float64 `toml:"sample_rate" json:"sample_rate,omitempty"`
}

What needs to change

Proposed implementation plan

1. Config alignment (~80 lines)

Update TracingConfig to match spec §4.1.3.6:

type TracingConfig struct {
    Endpoint    string            `toml:"endpoint" json:"endpoint,omitempty"`
    Headers     map[string]string `toml:"headers" json:"headers,omitempty"`
    TraceID     string            `toml:"trace_id" json:"traceId,omitempty"`
    SpanID      string            `toml:"span_id" json:"spanId,omitempty"`
    ServiceName string            `toml:"service_name" json:"serviceName,omitempty"`
    SampleRate  *float64          `toml:"sample_rate" json:"sampleRate,omitempty"`
}

Add opentelemetry alias in TOML (the spec uses opentelemetry, our current config uses tracing). Support both for backward compatibility.

Wire into StdinGatewayConfig + convertStdinConfig().

2. Validation (~60 lines)

In validation.go:

• endpoint must be HTTPS (when present)
• traceId must match ^[0-9a-f]{32}$ (after variable expansion)
• spanId must match ^[0-9a-f]{16}$ (after variable expansion)
• spanId without traceId → warning
• endpoint required when opentelemetry object is present

3. OTLP exporter + TracerProvider (~100 lines)

New internal/tracing/ package:

• InitTracerProvider(cfg *config.TracingConfig) → returns *sdktrace.TracerProvider or noop
• Uses OTLP/HTTP exporter with configured endpoint + headers
• Batch span processor (built-in retry + backoff)
• Constructs W3C parent context from traceId+spanId if provided
• Graceful shutdown via TracerProvider.Shutdown(ctx)

4. Instrumentation (~80 lines)

In callBackendTool() (unified.go):

ctx, span := tracer.Start(ctx, "mcp.tool_call",
    trace.WithAttributes(
        attribute.String("mcp.server", serverID),
        attribute.String("mcp.method", "tools/call"),
        attribute.String("mcp.tool", toolName),
    ))
defer span.End()

Root span created at startup in cmd/root.go.

5. Compliance tests (~200 lines)

T-OTEL-001 through T-OTEL-010 as described in spec §10.1.10.

New dependencies

go.opentelemetry.io/otel
go.opentelemetry.io/otel/sdk
go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp

Compliance test mapping

References

• Spec PR: gh-aw#24602
• Architecture analysis: #3177
• MCP Gateway Spec §4.1.3.6
• W3C Trace Context
• OTLP/HTTP Specification