[compliance] Compliance Gaps: keepaliveInterval and payloadSizeThreshold Configuration Handling

[github-actions]

MCP Gateway Compliance Review — 2026-04-06

Daily compliance review against the MCP Gateway Specification v1.11.0.

Commit reviewed: 9bd6e5b — Update stale features.difc-proxy references in workflow prompts

---

Summary

Found 3 compliance issues across 2 spec sections during today's review. The most impactful issue is a JSON schema gap that causes keepaliveInterval to be rejected when supplied via the JSON stdin format, even though it is a valid field per the spec and the Go implementation already supports it.

---

Important Issues (SHOULD / behavioral impact)

1. keepaliveInterval Missing from the Embedded JSON Schema

Specification Section: §4.1.3.5 — Keepalive Interval Configuration
Deep Link: https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md#4135-keepalive-interval-configuration

Requirement:

keepaliveInterval MUST be an integer when present. Any positive integer sets the keepalive interval in seconds.

Current State:

• StdinGatewayConfig in internal/config/config_stdin.go:40 correctly has a KeepaliveInterval *int field.
• The embedded JSON schema (internal/config/schema/mcp-gateway-config.schema.json) defines gatewayConfig with "additionalProperties": false.
• keepaliveInterval is not listed in gatewayConfig.properties in the schema.
• The fixSchemaBytes function in internal/config/validation_schema.go does add trustedBots dynamically, but does not add keepaliveInterval.

Gap:

When a user provides keepaliveInterval in a JSON stdin config, the schema validation step (validateJSONSchema in validation_schema.go:344) will reject it as an unknown field (because additionalProperties: false), even though the Go runtime supports it and the spec defines it as valid.

{
  "gateway": {
    "port": 8080,
    "domain": "localhost",
    "apiKey": "...",
    "keepaliveInterval": 300   // ← schema validation FAILS here
  }
}

Severity: Important — Users cannot use a documented spec feature via JSON stdin.

File References:

• internal/config/config_stdin.go:40 — KeepaliveInterval *int field exists in Go struct
• internal/config/schema/mcp-gateway-config.schema.json — schema missing keepaliveInterval
• internal/config/validation_schema.go:185-210 — fixSchemaBytes adds trustedBots but not keepaliveInterval
• internal/config/validation_schema.go:344-370 — validateJSONSchema enforces the schema

Suggested Fix:

Add keepaliveInterval to the embedded schema (or add it dynamically in fixSchemaBytes, as was done for trustedBots):

// In fixSchemaBytes, after adding trustedBots:
props["keepaliveInterval"] = map[string]interface{}{
    "type":        "integer",
    "description": "Keepalive ping interval in seconds for HTTP MCP backends. Use -1 to disable, 0 or unset for gateway default (1500s), or a positive integer for custom interval.",
}

---

2. payloadSizeThreshold in JSON Schema but Missing from StdinGatewayConfig

Specification Section: §4.1.3.3 — Payload Size Threshold
Deep Link: https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md#4133-payload-size-threshold

Requirement:

Threshold MUST be a positive integer representing bytes.
Gateway MUST compare actual payload size against threshold before deciding storage method.

Current State:

• The embedded JSON schema defines payloadSizeThreshold under gatewayConfig.properties with "type": "integer", "minimum": 1.
• StdinGatewayConfig in internal/config/config_stdin.go does not have a PayloadSizeThreshold field.
• Go's JSON unmarshaler silently ignores unknown fields.

Gap:

A user providing payloadSizeThreshold in JSON stdin config will:

1. Pass schema validation (field is in schema) — no error
2. Have the value silently ignored — it's never applied to GatewayConfig.PayloadSizeThreshold

The field is only configurable via TOML (payload_size_threshold), CLI flag (--payload-size-threshold), and environment variable (MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD). The JSON stdin format does not actually support it despite the spec listing it as a gateway config field.

Severity: Important — Schema claims to accept the field but silently ignores the value.

File References:

• internal/config/config_stdin.go:33-43 — StdinGatewayConfig struct (missing PayloadSizeThreshold)
• internal/config/schema/mcp-gateway-config.schema.json — schema defines payloadSizeThreshold
• internal/config/config_stdin.go:280-320 — StdinGatewayConfig conversion to GatewayConfig (no PayloadSizeThreshold mapping)

Suggested Fix:

Add PayloadSizeThreshold *int to StdinGatewayConfig and wire it in the conversion:

// StdinGatewayConfig
PayloadSizeThreshold *int `json:"payloadSizeThreshold,omitempty"`

// In conversion:
if stdinCfg.Gateway.PayloadSizeThreshold != nil && *stdinCfg.Gateway.PayloadSizeThreshold > 0 {
    gatewayConfig.PayloadSizeThreshold = *stdinCfg.Gateway.PayloadSizeThreshold
}

---

Minor Issues (MAY / best-practice)

3. TOML payload_size_threshold Not Validated as Positive Integer

Specification Section: §4.1.3.3
Deep Link: https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md#4133-payload-size-threshold

Requirement:

Threshold MUST be a positive integer representing bytes.

Current State:

• GatewayConfig.PayloadSizeThreshold int in config_core.go:112 — typed as int (no sign constraint)
• config_payload.go:25-26 only replaces 0 with the default; negative values are not caught
• The TOML validation path (config_core.go:330-390) does not call validateGatewayConfig

Gap:

A TOML config with payload_size_threshold = -1 would pass all validation and silently use a nonsensical negative threshold (all payloads would exceed it, triggering disk storage for everything).

Severity: Minor — Edge case, but spec says MUST be positive.

File References:

• internal/config/config_payload.go:25-26 — zero-check but no negative-check
• internal/config/config_core.go:330-390 — TOML validation path (no PayloadSizeThreshold check)

Suggested Fix:

Add explicit validation in the TOML path:

// In ParseConfig (config_core.go), after applyDefaults:
if cfg.Gateway.PayloadSizeThreshold < 0 {
    return nil, fmt.Errorf("gateway.payload_size_threshold must be a positive integer, got %d (spec §4.1.3.3)", cfg.Gateway.PayloadSizeThreshold)
}

---

Compliance Status

Section	Requirement	Status
§3.2.1	Containerization Requirement	✅ Compliant
§4.1	Configuration Format (stdin JSON)	✅ Compliant
§4.1.3.1	Payload Directory Path Validation	✅ Compliant
§4.1.3.2	Payload Path Prefix	✅ Compliant
§4.1.3.3	Payload Size Threshold	⚠️ Partial — JSON stdin silent-ignore; TOML missing negative-check
§4.1.3.4	Trusted Bot Identity	✅ Compliant
§4.1.3.5	Keepalive Interval	⚠️ Partial — JSON schema rejects the field
§4.1.3.6	OpenTelemetry Configuration	✅ Compliant
§4.2	Variable Expression Rendering	✅ Compliant
§5	Protocol Behavior	✅ Compliant
§7	Authentication	✅ Compliant
§8	Health Monitoring	✅ Compliant

---

Suggested Remediation Tasks

Task 1: Add keepaliveInterval to JSON schema

Description: Either add keepaliveInterval to the embedded schema file, or register it dynamically in fixSchemaBytes (the same approach used for trustedBots).
Files: internal/config/schema/mcp-gateway-config.schema.json, internal/config/validation_schema.go
Specification Reference: https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md#4135-keepalive-interval-configuration
Estimated Effort: Small (1–2 hours)

Task 2: Add PayloadSizeThreshold to StdinGatewayConfig

Description: Add PayloadSizeThreshold *int to StdinGatewayConfig and wire it into the GatewayConfig conversion logic, with positive-integer validation.
Files: internal/config/config_stdin.go, internal/config/validation.go
Specification Reference: https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md#4133-payload-size-threshold
Estimated Effort: Small (2–3 hours)

Task 3: Validate PayloadSizeThreshold in TOML path

Description: Add a positive-integer check for payload_size_threshold in the TOML config validation path.
Files: internal/config/config_core.go or internal/config/config_payload.go
Specification Reference: https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md#4133-payload-size-threshold
Estimated Effort: Trivial (< 1 hour)

---

References

• MCP Gateway Specification v1.11.0
• Commit reviewed: 9bd6e5b — Update stale features.difc-proxy references in workflow prompts
• Embedded schema version: v0.64.4 (vs spec v1.11.0 — version gap explains some missing fields)

Note

🔒 Integrity filter blocked 1 item

The following item were blocked because they don't meet the GitHub integrity level.

• get_file_contents get_file_contents: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".

To allow these resources, lower min-integrity in your GitHub frontmatter:

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

Generated by Daily Compliance Checker · ● 4.8M · ◷

[github-actions]

🤖 This is an automated response from Repo Assist.

I've verified all three compliance gaps reported here against the codebase and created a fix PR (#aw_pr3272fix):

Issue 1 confirmed (keepaliveInterval missing from schema): StdinGatewayConfig.KeepaliveInterval exists at line 40, but the embedded schema v0.64.4 does not list the field in gatewayConfig.properties. With additionalProperties: false, any JSON stdin config supplying keepaliveInterval will fail validation. Fix: register it in fixSchemaBytes alongside trustedBots.

Issue 2 confirmed (payloadSizeThreshold silently ignored): The schema lists the field (so validation passes), but StdinGatewayConfig has no PayloadSizeThreshold field — the value is dropped during JSON unmarshal and never reaches GatewayConfig.PayloadSizeThreshold. Fix: add the field and wire it in convertStdinConfig.

Issue 3 confirmed (payload_size_threshold allows negative in TOML): config_payload.go:25–26 only catches == 0 (replacing with default); a value of -1 passes all checks and silently makes every payload exceed the threshold, causing all payloads to be written to disk. Fix: add a negative-value guard in ParseConfig after applyDefaults.

All fixes are surgical and self-contained. Tests added for each case.

Generated by Repo Assist · ● 7M · ◷

To install this agentic workflow, run

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