[compliance] Compliance Gap: OTEL `headers` field still accepted in JSON stdin config (Spec §4.1.3.7 v1.14.0 Breaking Change)

[github-actions]

MCP Gateway Compliance Review — 2026-07-01

Summary

Found 1 compliance issue during daily review of commit 843d8d38 ([test] Add tests for guard.NewWasmGuardWithOptions coverage paths).

Spec Version: 1.14.0 (Breaking change — headers removal from JSON config)
Commits Reviewed: 843d8d38445e5516a37adf23a8d0533f47fac428 (HEAD, shallow clone)
Previous Review: 2026-06-30 (all other aspects confirmed compliant)

---

Critical/Important Issues (MUST violations)

1. OTEL headers field still present in JSON schema and StdinOpenTelemetryConfig

Specification Section: 4.1.3.7 — OpenTelemetry Configuration
Deep Link: https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md#4137-opentelemetry-configuration

Requirement:

From the Spec v1.14.0 changelog (Breaking change):

Breaking: headers field removed from opentelemetry configuration in JSON schema and gateway config spec (Section 4.1.3.7)

• Authentication headers MUST now be provided via the OTEL_EXPORTER_OTLP_HEADERS environment variable (standard OTel convention)
• Updated: JSON Schema — removed headers property from opentelemetryConfig definition

From spec Section 4.1.3.7 requirements:

Authentication headers MUST be provided via OTEL_EXPORTER_OTLP_HEADERS env var; the headers field is no longer accepted in the JSON config

The spec's field table for opentelemetry config (Section 4.1.3.7) lists only:

• endpoint (required)
• traceId (no)
• spanId (no)
• serviceName (no)

No headers field is listed.

Current State:

1. JSON Schema (internal/config/schema/mcp-gateway-config.schema.json lines 460–464) — still contains headers in opentelemetryConfig definition:

   "headers": {
     "type": "string",
     "description": "Comma-separated key=value HTTP headers for OTLP export requests. Supports ${VAR} expansion.",
     "minLength": 1
   }

2. Stdin config struct (internal/config/config_stdin.go line 81) — StdinOpenTelemetryConfig still has:

   // Headers is a comma-separated list of key=value HTTP headers for export requests
   Headers string `json:"headers,omitempty"`

3. Stdin converter (internal/config/config_tracing.go line 102) — still copies headers from stdin config:

   cfg.Gateway.Tracing = &TracingConfig{
       Endpoint:    otel.Endpoint,
       Headers:     otel.Headers,  // ← reads from JSON stdin
       ...
   }

4. Test (internal/config/load_from_stdin_coverage_test.go lines 183–217) — TestLoadFromStdin_OpenTelemetryHeaders explicitly verifies the non-compliant behavior:

   // verifies that gateway.opentelemetry.headers passes schema validation
   // and is converted into the runtime tracing config.

Gap:
The spec v1.14.0 Breaking change says headers must be REMOVED from the JSON schema and no longer accepted in the JSON stdin config. The implementation still accepts and processes it.

Note on resolveHeaders priority: The current implementation in internal/tracing/config_resolver.go gives cfg.Headers (from JSON/TOML config) higher priority than OTEL_EXPORTER_OTLP_HEADERS env var — the env var is only a fallback. The spec requires the env var to be the only way to pass headers in the JSON config context.

Severity: Important (MUST violation / Breaking spec change)

File References:

• internal/config/schema/mcp-gateway-config.schema.json — opentelemetryConfig.headers property (lines 460–464)
• internal/config/config_stdin.go:81 — StdinOpenTelemetryConfig.Headers field
• internal/config/config_tracing.go:102 — stdin converter reads otel.Headers
• internal/config/load_from_stdin_coverage_test.go:183–217 — test verifies non-compliant behavior

Note: The TOML config (TracingConfig.Headers with toml:"headers") is a separate concern — the spec's breaking change specifically targets the JSON stdin config, so TOML support for headers may be retained.

Suggested Fix:

1. Remove headers from JSON schema — delete the headers property from the opentelemetryConfig definition in mcp-gateway-config.schema.json.

2. Remove Headers from StdinOpenTelemetryConfig — delete the Headers string field in config_stdin.go.

3. Update stdin converter — remove Headers: otel.Headers from the stdin→config conversion in config_tracing.go.

4. Update resolveHeaders — once the stdin-config field is removed, the env var becomes the primary/only source. Consider logging a clear warning if a caller still somehow passes headers config so the change is discoverable.

5. Update test — replace TestLoadFromStdin_OpenTelemetryHeaders with a test that verifies headers is rejected (fails schema validation) when provided in the JSON stdin config.

Estimated Effort: Small (1–2 hours)

---

Compliance Status (Full)

Spec Section	Area	Status
§3.2.1	Containerization Requirement	✅ Compliant
§4.1	Configuration Format (JSON stdin)	✅ Compliant
§4.1.3.7	OpenTelemetry headers removal	❌ Non-compliant (this issue)
§4.2	Variable Expression Rendering	✅ Compliant
§4.3	Configuration Validation	✅ Compliant
§5	Protocol Behavior	✅ Compliant
§6	Server Isolation	✅ Compliant
§7	Authentication	✅ Compliant
§8	Health Monitoring	✅ Compliant
§9	Error Handling	✅ Compliant
§10	Guard Policy (incl. refusal-labels)	✅ Compliant

---

Recent Changes Reviewed

• Commit: 843d8d38 — [test] Add tests for guard.NewWasmGuardWithOptions coverage paths ([test] Add tests for guard.NewWasmGuardWithOptions coverage paths #8455)
  • Pure test coverage improvement for the WASM guard: custom stdout/stderr wiring, empty name fallback, compilation cache paths
  • No compliance-impacting code changes
  • All new tests are compliant with existing spec requirements

---

References

• MCP Gateway Specification §4.1.3.7
• Spec v1.14.0 Changelog — Breaking: headers removal
• Previous compliance review: [compliance] Compliance Gap: specVersion outdated + refusal-labels guard policy field missing #7646 (spec version and refusal-labels — resolved)

Generated by Daily Compliance Checker · 196.4 AIC · ⊞ 9.4K · ◷

[github-actions]

🤖 This is an automated response from Repo Assist.

I've verified this compliance gap against the codebase. The diagnosis is accurate — the headers field is still fully accepted in the JSON stdin config path, which is a direct violation of the Spec v1.14.0 breaking change.

Verification of the four affected locations:

1. internal/config/schema/mcp-gateway-config.schema.json — opentelemetryConfig still has headers as an optional property (currently accepted, should be rejected/removed).

2. internal/config/config_stdin.go:81 — StdinOpenTelemetryConfig.Headers string field still present.

3. internal/config/config_tracing.go:102 — Headers: otel.Headers still copied from stdin config into TracingConfig.

4. internal/config/load_from_stdin_coverage_test.go — TestLoadFromStdin_OpenTelemetryHeaders currently asserts the opposite of what the spec requires.

One additional concern: Beyond just removing the field, internal/tracing/config_resolver.go's resolveHeaders currently gives the config-supplied cfg.Headers higher priority than OTEL_EXPORTER_OTLP_HEADERS. After the fix, the env var should become the only source for JSON stdin users, so resolveHeaders should prefer the env var when headers arrive from that context (or simply: removing the stdin field makes the config value nil, and the fallback to env var handles it automatically).

Suggested fix sequence:

1. Remove headers from opentelemetryConfig in the JSON schema.
2. Remove Headers string from StdinOpenTelemetryConfig in config_stdin.go.
3. Remove Headers: otel.Headers from the converter in config_tracing.go.
4. Update TestLoadFromStdin_OpenTelemetryHeaders → rename to TestLoadFromStdin_OpenTelemetryHeaders_Rejected and assert that providing headers in the JSON config either fails schema validation or is silently ignored (depending on desired strictness).
5. Optionally add a log warning in resolveHeaders if cfg.Headers is non-empty (shouldn't happen after fix, but useful during migration).

Note: TOML config's TracingConfig.Headers field is a separate concern — per the issue, only the JSON stdin config path is affected by this breaking change, so TOML support can remain.

Estimated effort matches the issue's assessment: small, ~1–2 hours.

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• proxy.golang.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "proxy.golang.org"

See Network Configuration for more information.

Generated by Repo Assist · 288.1 AIC · ⊞ 12.4K · ◷
_{Comment /repo-assist to run again}

_{Add this agentic workflow to your repo}

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/repo-assist.md@851905c06e905bf362a9f6cc54f912e3df747d55