[compliance] Stdout Configuration Output Missing Required Headers Object

[github-actions]

MCP Gateway Compliance Review - 2026-01-12

Summary

Found 1 critical compliance issue during daily review of commit b5c9ec1 against MCP Gateway Specification v1.3.0.

Recent Changes Reviewed

Commit SHA: b5c9ec1114c1a5fbf2919742599f98d3ce39128e
Commit Message: "Merge pull request #183 from githubnext/copilot/fix-gateway-connection-error"

Review Scope: Full systematic review of all specification sections against current implementation.

---

Critical Issues (MUST violations)

1. Stdout Configuration Output - Conditional Headers Object

Specification Section: 5.4 Stdout Configuration Output
Deep Link: https://github.com/githubnext/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md#54-stdout-configuration-output

Specification Requirement (Section 5.4, lines 536-538):

REQUIRED: The headers object MUST be present in each server configuration and MUST include the Authorization header with the API key value. The Authorization header value MUST contain the API key directly, NOT using the Bearer authentication scheme. The gateway is responsible for generating and including appropriate authentication credentials - client-side configuration converters MUST NOT modify or supplement the headers provided by the gateway.

Current State:

In internal/cmd/root.go lines 286-292:

// Add auth headers per MCP Gateway Specification Section 5.4
// Authorization header contains API key directly (not Bearer scheme per spec 7.1)
if apiKey != "" {
    serverConfig["headers"] = map[string]string{
        "Authorization": apiKey,
    }
}

Gap:

1. The headers object is only added conditionally when apiKey != ""
2. The specification states it MUST be present (unconditional requirement)
3. According to Section 4.1.3, apiKey is a required field in gateway configuration, so it should always be present
4. The current implementation creates a logical inconsistency where the gateway might not include headers even though the spec requires them

Test Evidence:

In internal/cmd/stdout_config_test.go lines 199-202:

// If no API key, headers should not be present
if headers, ok := serverConfig["headers"]; ok {
    t.Errorf("Server '%s' should not have headers when no API key is configured, got: %v", serverName, headers)
}

This test explicitly verifies that headers are NOT present when there's no API key, which contradicts the specification requirement.

Impact:

• Severity: Critical (MUST violation)
• Compliance Test: T-OUT-005 (Each server configuration has "headers" object with "Authorization" header) - FAILING
• User Impact: Client-side tools may not receive proper authentication headers in the output configuration

File References:

• internal/cmd/root.go:286-292 (conditional headers logic)
• internal/cmd/stdout_config_test.go:199-202 (incorrect test assertion)

---

Compliance Status Summary

Specification Section	Status	Notes
✅ 3.2.1 Containerization Requirement	Compliant	Stdio servers require container field, command field rejected
✅ 4.1 Configuration Format	Compliant	JSON schema validation, proper field validation
✅ 4.2 Variable Expression Rendering	Compliant	Fail-fast on undefined variables, proper error messages
✅ 4.3 Configuration Validation	Compliant	Schema validation with helpful error messages
✅ 5.1 HTTP Server Interface	Compliant	POST /mcp/{server-name}, GET /health, POST /close
✅ 5.1.3 Close Endpoint	Compliant	Idempotency, authentication, proper responses
❌ 5.4 Stdout Configuration Output	Non-compliant	Headers object conditionally included
✅ 6. Server Isolation	Compliant	Container isolation, resource isolation
✅ 7. Authentication	Compliant	Plain API key format (not Bearer), proper validation
✅ 8.1.1 Health Endpoint	Compliant	Includes specVersion and gatewayVersion fields
✅ 9. Error Handling	Compliant	Proper error codes, fail-fast behavior

Overall Compliance: 10/11 sections compliant (90.9%)

---

Suggested Remediation

Task 1: Always Include Headers Object in Stdout Configuration

Priority: Critical
Estimated Effort: Small (1-2 hours)

Changes Required:

1. Update internal/cmd/root.go (lines 286-292):

   // Add auth headers per MCP Gateway Specification Section 5.4
   // Per spec: headers object MUST always be present with Authorization header
   // Authorization header contains API key directly (not Bearer scheme per spec 7.1)
   serverConfig["headers"] = map[string]string{
       "Authorization": apiKey,
   }

   Rationale: Remove the conditional check since:

   • apiKey is required per Section 4.1.3
   • Schema validation enforces this (see internal/config/schemas/mcp-gateway-config.schema.json)
   • Headers MUST always be present per Section 5.4

2. Update internal/cmd/stdout_config_test.go (lines 199-202):

   Remove or update this test case:

   // Per spec 5.4: headers object MUST always be present
   headers, ok := serverConfig["headers"].(map[string]interface{})
   if !ok {
       t.Errorf("Server '%s' missing required headers object (spec 5.4)", serverName)
       continue
   }
   
   authHeader, ok := headers["Authorization"].(string)
   if !ok {
       t.Errorf("Server '%s' missing required Authorization header (spec 5.4)", serverName)
       continue
   }
   
   // Verify Authorization header has correct value
   if tt.wantAPIKey != "" && authHeader != tt.wantAPIKey {
       t.Errorf("Server '%s' Authorization header = %v, want %v", serverName, authHeader, tt.wantAPIKey)
   }

3. Add compliance test for T-OUT-005:

   • Create test verifying headers object is always present
   • Verify Authorization header is always included
   • Verify Authorization header contains API key directly (not Bearer)

Specification Reference:

• https://github.com/githubnext/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md#54-stdout-configuration-output
• https://github.com/githubnext/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md#1017-configuration-output-tests

Related Compliance Tests:

• T-OUT-005: Each server configuration has "headers" object with "Authorization" header
• T-OUT-006: Authorization header contains API key directly (not Bearer scheme)

---

References

• MCP Gateway Specification v1.3.0
• Last review: Previous review found health endpoint critical issue (now resolved)
• Commits reviewed: b5c9ec1114c1a5fbf2919742599f98d3ce39128e

Review Metadata

• Review Date: 2026-01-12T05:48:47Z
• Specification Version: 1.3.0
• Gateway Commit: b5c9ec1
• Issues Found: 1 critical
• Issues Resolved Since Last Review: 1 (health endpoint version fields)

AI generated by Daily Compliance Checker

[pelikhan]

Spec needs update