MCP Gateway Compliance Review — 2026-06-04

Summary

Found 2 compliance issues introduced or exposed by commit 27fc0d0 (Reconcile configuration/docs semantics and Go version guidance with current implementation). Both relate to the gateway.opentelemetry block in JSON stdin configuration.

Commit Reviewed

• SHA: 27fc0d0 (HEAD → main)
• Title: Reconcile configuration/docs semantics and Go version guidance with current implementation (Reconcile configuration/docs semantics and Go version guidance with current implementation #6998)
• Key changes: corrected sample_rate docs support matrix, updated rate_limit_threshold/rate_limit_cooldown docs, added tool_response_filters snake_case note, fixed Go version check logic

Important Issues (SHOULD violations)

Issue 1: gateway.opentelemetry.headers silently blocked by JSON schema

Specification Section: 4.1.3.6 OpenTelemetry Configuration
Deep Link: https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md#4136-opentelemetry-tracing

Requirement:

The gateway SHOULD support all documented configuration fields in the JSON stdin format.

Current State:

The embedded JSON schema (internal/config/schema/mcp-gateway-config.schema.json, v0.64.4) defines opentelemetryConfig with additionalProperties: false and only four properties: endpoint, traceId, spanId, serviceName. The headers field is absent from this schema definition.

However:

• StdinOpenTelemetryConfig in internal/config/config_stdin.go:55 does have a Headers field
• The stdin converter in internal/config/config_tracing.go:133–139 does copy Headers into TracingConfig
• docs/CONFIGURATION.md:448 documents headers as a valid JSON stdin field

Because validateJSONSchema() in internal/config/validation_schema.go:394 runs the full JSON against the embedded schema before the struct is populated, any JSON stdin config that includes gateway.opentelemetry.headers will be rejected with a schema validation error:

additional property "headers" is not allowed (at gateway.opentelemetry)

Gap:

• internal/config/schema/mcp-gateway-config.schema.json — opentelemetryConfig definition is missing headers
• internal/config/validation_schema.go — fixSchemaBytes() adds missing fields to other definitions (e.g., trustedBots, keepaliveInterval, guard-policies) but does not add headers to opentelemetryConfig

Severity: Important (SHOULD violation — documented field is blocked by schema)

File References:

• internal/config/schema/mcp-gateway-config.schema.json — definitions.opentelemetryConfig (line ~200)
• internal/config/validation_schema.go:218–245 — fixSchemaBytes() patching logic
• internal/config/config_stdin.go:55 — Headers field present in struct
• internal/config/config_tracing.go:133–139 — converter copies Headers
• docs/CONFIGURATION.md:448 — documents headers as valid JSON stdin field

Suggested Fix — Option A (preferred): Add a fix in fixSchemaBytes() in internal/config/validation_schema.go to inject the headers property into opentelemetryConfig, similar to how keepaliveInterval and trustedBots are injected into gatewayConfig:

// Add headers to opentelemetryConfig (supported by implementation but absent from schema v0.64.4)
if opentelemetryConfig, ok := definitions["opentelemetryConfig"].(map[string]interface{}); ok {
    if props, ok := opentelemetryConfig["properties"].(map[string]interface{}); ok {
        props["headers"] = map[string]interface{}{
            "type":        "string",
            "description": "Comma-separated key=value HTTP headers for OTLP export requests. Supports ${VAR} expansion.",
        }
        logSchema.Print("Added headers field to opentelemetryConfig")
    }
}

Suggested Fix — Option B: Update the bundled schema file directly to add headers to opentelemetryConfig.

Minor Issues (documentation regressions)

Issue 2: sampleRate documented as JSON stdin field but not implemented (regression from #6998)

Specification Section: 4.1.3.6 OpenTelemetry Configuration
Deep Link: https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md#4136-opentelemetry-tracing

Requirement:

Documentation MUST accurately reflect the supported configuration interface.

Current State:

Commit 27fc0d0 updated docs/CONFIGURATION.md:451 to say:

sample_rate (TOML) / sampleRate (JSON stdin) | Fraction of traces sampled and exported (0.0–1.0). Also available via CLI --otlp-sample-rate.

However, sampleRate in JSON stdin does not work:

1. Schema blocks it: opentelemetryConfig has additionalProperties: false, so providing sampleRate in gateway.opentelemetry via JSON stdin causes schema validation failure.
2. StdinOpenTelemetryConfig has no field: internal/config/config_stdin.go:48–65 — StdinOpenTelemetryConfig has no SampleRate field, so even if the schema were fixed, the value would not be parsed.
3. Converter does not copy it: internal/config/config_tracing.go:133–139 — the RegisterStdinConverter does not set SampleRate when building TracingConfig from StdinOpenTelemetryConfig.

sampleRate does work via:

• TOML: [gateway.opentelemetry] sample_rate = 0.5 (uses TracingConfig.SampleRate with TOML tag)
• CLI: --otlp-sample-rate 0.5

Gap: The CONFIGURATION.md entry sampleRate (JSON stdin) is inaccurate — this was a documentation regression introduced in commit 27fc0d0.

Severity: Minor (documentation regression — feature described in docs does not work)

File References:

• docs/CONFIGURATION.md:451 — incorrect sampleRate (JSON stdin) column added by Reconcile configuration/docs semantics and Go version guidance with current implementation #6998
• internal/config/config_stdin.go:48–65 — StdinOpenTelemetryConfig struct (missing SampleRate)
• internal/config/config_tracing.go:125–143 — stdin converter (does not copy SampleRate)
• internal/config/schema/mcp-gateway-config.schema.json — opentelemetryConfig (no sampleRate field)

Suggested Fix: Either:

• (A) Remove sampleRate (JSON stdin) from the CONFIGURATION.md table and note that sampleRate is TOML/CLI-only (simplest, accurate)
• (B) Implement JSON stdin support: add SampleRate *float64 \json:"sampleRate,omitempty"`toStdinOpenTelemetryConfig, copy it in the converter, and inject the field into the schema via fixSchemaBytes()`

Compliance Status

Suggested Remediation Tasks

Task 1: Inject headers into opentelemetryConfig in fixSchemaBytes()

Description: Add a patch in internal/config/validation_schema.go's fixSchemaBytes() to add the headers field to the opentelemetryConfig schema definition, mirroring the pattern used for keepaliveInterval and trustedBots in gatewayConfig. Also add a test that headers in gateway.opentelemetry passes LoadFromStdin().
Files: internal/config/validation_schema.go, internal/config/load_from_stdin_coverage_test.go (or validation_otel_test.go)
Specification Reference: https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md#4136-opentelemetry-tracing
Estimated Effort: Small (1–2 hours)

Task 2: Resolve sampleRate JSON stdin discrepancy

Description: Either remove sampleRate (JSON stdin) from CONFIGURATION.md (simplest fix, requires only a docs change) or implement full JSON stdin support for sampleRate (requires: add field to StdinOpenTelemetryConfig, copy in converter, add schema injection, add tests).
Files: docs/CONFIGURATION.md (required); optionally internal/config/config_stdin.go, internal/config/config_tracing.go, internal/config/validation_schema.go
Specification Reference: https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md#4136-opentelemetry-tracing
Estimated Effort: Small (30 min for docs-only fix; 2–3 hours for full implementation)

References

• MCP Gateway Specification
• Commit reviewed: 27fc0d0 (grafted, HEAD → main)
• Previous review: all other aspects passing (cache from 2026-06-03)

tools:
  github:
    min-integrity: approved  # merged | approved | unapproved | none

Generated by Daily Compliance Checker · sonnet46 6.5M · ◷