[compliance] Compliance Gap: Spec 1.17.0 removes gateway.apiKey and adds agentIds (plural) — implementation not updated

[github-actions]

Summary

Daily compliance review found the MCP Gateway Specification was updated to Version 1.17.0 (from 1.16.0), but this repository's implementation has not been updated to match. This is a "MUST"-level breaking-change gap.

Recent Changes Reviewed

• HEAD commit 146de0b — "Upgrade workflows to gh-aw v0.87.9 pre-release (Upgrade workflows to gh-aw v0.87.9 pre-release #12113)". This commit is a workflow/tooling upgrade (devcontainer, CI actions, compiled workflow files) and does not touch internal/config, internal/server, or internal/launcher. No regression was introduced by this commit itself.
• The gap below was found by comparing the current implementation against the live specification fetched from github/gh-aw@main (spec Version 1.17.0), not against the local commit diff.

Critical Issue (MUST violation)

1. gateway.apiKey still present in published/generated schema; agentIds (plural) not implemented

Specification Section: 4.1.3.9 "Agent Identifier Configuration (agentId / agentIds)" and Change Log "Version 1.17.0 (Draft)"

Deep Link: https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md#4139-agent-identifier-configuration-agentid--agentids

Requirement:

"BREAKING: Removed gateway.apiKey from the specification and published schemas... Implementations MAY continue to accept the legacy api_key/apiKey spelling internally for backward compatibility with existing deployments, but apiKey MUST NOT appear in generated or published configuration; agentId or agentIds MUST be used instead."

"A gateway configuration configuration MUST select exactly one of agentId or agentIds. Specifying both, or neither, MUST be rejected as invalid configuration."

"agentIds (array of strings): one or more agent/session identifiers, enabling a primary agent and enclave sessions to share one gateway instance while retaining independent DIFC state and policies."

Current State:

• internal/config/schema/mcp-gateway-config.schema.json — definitions.gatewayConfig.properties still publishes apiKey (/definitions/gatewayConfig/properties/apiKey), which the spec now says MUST NOT appear in published/generated configuration.
• No agentIds field exists anywhere in the schema or Go config structs (internal/config/config_core.go, internal/config/config_stdin.go) — only singular AgentID/agentId and the legacy APIKey/apiKey alias are supported.
• There is no validation enforcing "exactly one of agentId/agentIds" since agentIds doesn't exist to conflict with.
• internal/server/unified.go:40 — MCPGatewaySpecVersion = "1.16.0" — the spec-version constant is stale relative to the now-current spec version 1.17.0 (though internal apiKey acceptance for backward compat is still allowed per spec, so this may be considered acceptable pending an intentional decision on agentIds support).

Gap:

1. The published JSON schema exposes apiKey as a first-class property, contradicting the spec's "MUST NOT appear in generated or published configuration."
2. agentIds (plural array form) is entirely unimplemented — no schema property, no Go struct field, no mutual-exclusion validation, no TOML agent_ids support.
3. MCPGatewaySpecVersion constant not bumped to reflect the new spec version.

Severity: Critical (MUST violation) for items 1–2; Important for item 3 (constant tracking, consistent with prior similar resolved issues in this repo's history).

File References:

• internal/config/schema/mcp-gateway-config.schema.json (gatewayConfig.properties.apiKey)
• internal/config/config_core.go (GatewayConfig struct, ~lines 105–251, no AgentIDs/agentIds field or mutual-exclusion check)
• internal/config/config_stdin.go (StdinGatewayConfig struct, ~lines 38–78, no agentIds field)
• internal/server/unified.go:40 (MCPGatewaySpecVersion = "1.16.0")

Suggested Fix / Remediation Tasks:

Task 1: Remove apiKey from published schema, keep internal backward-compat only

Description: Remove the apiKey property from internal/config/schema/mcp-gateway-config.schema.json (gatewayConfig.properties) so it no longer appears in generated/published configuration, while retaining internal Go-level acceptance of legacy api_key/apiKey fields for backward compatibility (already implemented via normalizeAgentID).
Files: internal/config/schema/mcp-gateway-config.schema.json
Estimated Effort: Small (1-2 hours)

Task 2: Implement agentIds (plural) support

Description: Add an AgentIDs []string field to GatewayConfig (TOML agent_ids) and to StdinGatewayConfig (JSON agentIds), add the corresponding schema property (array of non-empty strings, minItems 1), and enforce that a gateway configuration selects exactly one of agentId/agentIds (reject both-set and neither-set as invalid). Update config_core.go's normalizeAgentID/validation logic and config_stdin.go's conversion path accordingly.
Files: internal/config/config_core.go, internal/config/config_stdin.go, internal/config/schema/mcp-gateway-config.schema.json, internal/config/validation.go (or wherever mutual-exclusion validation should live)
Estimated Effort: Medium (4-6 hours, plus tests)

Task 3: Update spec version constant

Description: Update MCPGatewaySpecVersion in internal/server/unified.go:40 from "1.16.0" to "1.17.0" once Tasks 1–2 are complete (or immediately if the team decides current behavior is otherwise compliant with 1.17.0's other requirements).
Files: internal/server/unified.go
Estimated Effort: Trivial (<1 hour, following prior pattern from issues #7646 and spec-version-1.15.0 resolution)

Compliance Status

• ✅ Configuration Format (Section 4.1): Compliant (aside from apiKey/agentIds gap above)
• ✅ Variable Expansion (Section 4.2): Compliant
• ✅ Containerization (Section 3.2.1): Compliant — no command field support in JSON stdin path (internal/config/config_stdin.go), stdio requires container
• ✅ Protocol Behavior (Section 5): Compliant
• ✅ Server Isolation (Section 6): Compliant
• ❌ Agent Identifier Configuration (Section 4.1.3.9, new in 1.17.0): Non-compliant — see issue above
• ✅ Health Monitoring (Section 8): Compliant
• ✅ Error Handling (Section 9): Compliant

References

• MCP Gateway Specification (fetched live, Version 1.17.0)
• Spec Change Log: https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md#version-1170-draft
• Prior spec-version-constant issue (pattern to follow): [compliance] Compliance Gap: specVersion outdated + refusal-labels guard policy field missing #7646
• Commit reviewed: 146de0b (workflow tooling upgrade only, no gateway core changes)

Generated by Daily Compliance Checker · copilot · auto · 61.2 AIC · ⊞ 14.6K · ◷

[github-actions]

🤖 This is an automated response from Repo Assist.

Thanks for the detailed compliance report! I checked the current state of the codebase against the three remediation tasks:

• Task 1 (remove apiKey from published schema): Already done. internal/config/schema/mcp-gateway-config.schema.json has no apiKey property in gatewayConfig.properties — only agentId/agentIds are published, with a oneOf constraint requiring exactly one of them.
• Task 2 (implement agentIds plural support): Already done. GatewayConfig.AgentIDs []string (TOML agent_ids) and StdinGatewayConfig's agentIds both exist, validateAgentIDs enforces the non-empty-array rule, and both the TOML loader (config_core.go) and stdin path reject combining agent_ids/agentIds with agent_id/api_key/apiKey (mutual exclusion).
• Task 3 (bump spec version constant): Still open. internal/server/unified.go:40 has MCPGatewaySpecVersion = "1.16.0", which should be "1.17.0" now that Tasks 1–2 are complete.

So it looks like most of this gap was already remediated (likely by a recent PR), and only the trivial constant bump remains. I'd suggest closing this issue once that one-line change lands, or scoping a follow-up just for the version bump — happy to open that PR if useful.

Warning

Firewall blocked 1 domain

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

• api.github.com

[!TIP]
api.github.com is blocked because GitHub API access uses the built-in GitHub tools by default. Instead of adding api.github.com to network.allowed, use tools.github.mode: gh-proxy for direct pre-authenticated GitHub CLI access without requiring network access to api.github.com:

tools:
  github:
    mode: gh-proxy

See GitHub Tools for more information on gh-proxy mode.

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

network:
  allowed:
    - defaults
    - "api.github.com"

See Network Configuration for more information.

Generated by Repo Assist · copilot · auto · 182.5 AIC · ⊞ 18.9K · ◷
_{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