[compliance] TOML Configuration Violates Containerization Requirement

[github-actions]

MCP Gateway Compliance Review - February 17, 2026

Summary

Found 1 critical compliance issue during daily review of commit bb96a20419067e109cc24e21b725f78f2eca663e.

The gateway's TOML configuration format allows arbitrary command execution (e.g., command = "node", command = "python"), which directly violates the MCP Gateway Specification requirement that all stdio-based MCP servers MUST be containerized.

---

Critical Issue: TOML Configuration Allows Non-Containerized Commands

Specification Section

3.2.1 Containerization Requirement

Deep Link: https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md#321-containerization-requirement

Specification Requirement

"Stdio-based MCP servers MUST be containerized. The gateway SHALL NOT support direct command execution without containerization (stdio+command) because:

1. Containerization provides necessary process isolation and security boundaries
2. Containers enable reproducible environments across different deployment contexts
3. Container images provide versioning and dependency management
4. Containerization ensures portability and consistent behavior

Direct command execution of stdio servers (e.g., command: "node server.js" without a container) is explicitly NOT SUPPORTED by this specification."

Current State

TOML configuration (config.toml) allows arbitrary commands:

[servers.filesystem]
command = "node"
args = ["/path/to/filesystem-server.js"]

From README.md lines 88-102:

"TOML configuration uses command and args fields directly for maximum flexibility"

"Note: In TOML format, you specify the command and args directly. This allows you to use any command (docker, node, python, etc.)."

The code only WARNS but does NOT reject non-containerized commands:

// internal/launcher/launcher.go:127-133
isDirectCommand := serverCfg.Command != "docker"
if l.runningInContainer && isDirectCommand {
    l.logSecurityWarning(serverID, serverCfg)
}

This warning only triggers when the gateway itself is running inside a container AND a non-Docker command is used. It does NOT enforce the specification requirement.

Gap

Compliance Violation:

1. ❌ TOML format allows command = "node", command = "python", etc.
2. ❌ No validation rejects non-containerized stdio servers
3. ❌ Documentation explicitly promotes arbitrary command usage
4. ✅ JSON stdin format IS compliant (requires container field, rejects command field)

Severity: Critical (MUST/SHALL violation)

File References

• internal/config/config_core.go:92-93 - Command field in ServerConfig struct
• internal/launcher/launcher.go:127-133 - Warning logic instead of rejection
• internal/launcher/log_helpers.go - logSecurityWarning function
• README.md:88-102 - Documents arbitrary command support
• README.md:146-147 - Notes command field support in TOML
• config.example.toml:45-47 - Example showing command = "docker"

Impact Analysis

Specification Compliance:

• Violates Section 3.2.1 (Containerization Requirement) - MUST requirement
• Non-conforming implementation per Section 2.1 (Conformance Classes)

Security Impact:

• Breaks isolation guarantees promised by the specification
• Allows arbitrary process execution without containerization
• Inconsistent security posture between TOML and JSON configurations

User Impact:

• Users following TOML documentation will create non-compliant configurations
• Configurations work but violate spec, creating portability issues
• Silent compliance violations (no clear error message)

---

Suggested Remediation Tasks

Task 1: Add TOML Validation to Reject Non-Docker Commands

Description: Extend validation to reject TOML configurations where command != "docker" for stdio servers

Implementation Approach:

1. Add validation function in internal/config/validation.go:

   func validateStdioCommandIsDocker(servers map[string]*ServerConfig) error {
       for name, cfg := range servers {
           if cfg.Type == "stdio" && cfg.Command != "docker" {
               return fmt.Errorf("server '%s': stdio servers must use containerized execution (command must be 'docker', got '%s'). See specification section 3.2.1", name, cfg.Command)
           }
       }
       return nil
   }

2. Call validation in LoadFromFile() after TOML parsing

3. Return error with clear specification reference

Files to Modify:

• internal/config/validation.go - Add validation function
• internal/config/config_core.go - Call validation in LoadFromFile()

Specification Reference: https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md#321-containerization-requirement

Estimated Effort: Small (2-3 hours)

Testing:

• Add test case in internal/config/validation_test.go with command = "node"
• Verify error message references specification section
• Ensure Docker commands still work: command = "docker"

---

Task 2: Update Documentation to Remove Non-Containerized Examples

Description: Remove documentation that promotes arbitrary command usage, align with specification

Changes Required:

1. README.md (lines 86-102):

   • Remove: "This allows you to use any command (docker, node, python, etc.)"
   • Update: "TOML configuration requires command = "docker" for stdio servers per specification"
   • Add reference to specification requirement

2. config.example.toml:

   • Add comment: # Required: Must be "docker" for stdio servers (spec requirement)
   • Remove any examples suggesting non-Docker commands are allowed

3. AGENTS.md:

   • Update agent instructions to clarify containerization requirement
   • Add specification reference

Specification Reference: https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md#321-containerization-requirement

Estimated Effort: Small (1-2 hours)

---

Task 3: Consider Deprecating TOML Format in Favor of JSON Stdin

Description: Evaluate whether TOML format should be deprecated given JSON stdin is spec-compliant

Rationale:

• JSON stdin format already enforces containerization (uses container field)
• TOML format creates maintenance burden and compliance risks
• Specification defines JSON stdin format as the primary configuration method
• TOML format is a local development convenience, not required by spec

Action Items:

1. Document JSON stdin as the recommended configuration format
2. Consider marking TOML as deprecated in next release
3. Provide migration guide from TOML to JSON stdin
4. Keep TOML support for backward compatibility but with clear deprecation notice

Specification Reference: https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md#41-configuration-format

Estimated Effort: Medium (4-6 hours for documentation and migration guide)

---

Compliance Status After Review

Configuration Validation (Section 4)

• ✅ JSON stdin format: Compliant - Rejects command field, requires container
• ❌ TOML file format: Non-compliant - Allows arbitrary commands
• ✅ Variable expansion: Compliant - Fails fast on undefined variables
• ✅ Schema validation: Compliant - Proper error messages with JSON paths
• ✅ Unknown field detection: Compliant - Warnings for typos

Containerization (Section 3.2.1)

• ❌ Non-compliant - TOML format violates containerization requirement
• ✅ JSON stdin implementation is compliant
• ⚠️ Warning system exists but doesn't enforce requirement

Protocol Translation (Section 5)

• ✅ Compliant - HTTP endpoints, JSON-RPC 2.0, proper routing
• ✅ Timeout handling implemented
• ✅ Protocol translation functional

Server Isolation (Section 6)

• ✅ Compliant - Container isolation working when Docker is used
• ⚠️ Compromised by TOML allowing non-containerized execution

Authentication (Section 7)

• ✅ Compliant - API key authentication via Authorization header
• ✅ Health endpoint exempt from auth
• ✅ No plaintext logging of API keys

Health Monitoring (Section 8)

• ✅ Compliant - /health endpoint functional
• ✅ Server status reporting
• ✅ Health check implementation

Error Handling (Section 9)

• ✅ Compliant - Detailed startup failure messages
• ✅ JSON-RPC error format
• ✅ Proper error codes

---

Overall Assessment

Overall Compliance: ⚠️ Partially Conforming

Per specification Section 2.1 (Conformance Classes):

"A partially conforming MCP Gateway implementation is one that satisfies all MUST requirements but MAY lack support for optional features marked with SHOULD or MAY."

The gateway violates a MUST requirement (Section 3.2.1), making it a non-conforming implementation when TOML configuration is used.

Recommendation: Implement Task 1 (validation) as highest priority to achieve full conformance with the MCP Gateway Specification.

---

References

• MCP Gateway Specification v1.8.0
• Last commit reviewed: bb96a20419067e109cc24e21b725f78f2eca663e
• Review date: February 17, 2026
• Compliance test reference: T-CFG-001 (Valid stdio server configuration)

Generated by Daily Compliance Checker

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this critical compliance issue as a high priority for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the TOML configuration validation requirements and create a pull request with the fix to enforce containerization requirements.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster