Add guard-policies support to MCP gateway config

- Added GuardPolicies field to ServerConfig (TOML and JSON formats)
- Updated JSON schema URL to fetch latest spec from main branch
- Added guard-policies to known fields in StdinServerConfig unmarshal
- Preserved guard-policies in config conversion for both stdio and HTTP servers
- Added comprehensive tests for guard-policies in both TOML and JSON formats
- Updated config examples with GitHub guard policy examples
- Updated README with detailed guard-policies documentation and examples
- Fixed test assertion to handle new error message format

Co-authored-by: lpcox <15877973+lpcox@users.noreply.github.com>

Author: Claude

README.md

@@ -130,6 +130,12 @@ For the complete JSON configuration specification with all validation rules, see
       "env": {
         "GITHUB_PERSONAL_ACCESS_TOKEN": "",
         "EXPANDED_VAR": "${MY_HOME}/config"
+      },
+      "guard-policies": {
+        "github": {
+          "owner": "github",
+          "repos": ["gh-aw-mcpg", "gh-aw"]
+        }
       }
     }
   },
@@ -182,6 +188,21 @@ For the complete JSON configuration specification with all validation rules, see
 
 - **`url`** (required for http): HTTP endpoint URL for `type: "http"` servers
 
+- **`guard-policies`** (optional): Guard policies for access control at the MCP gateway level
+  - Structure is server-specific and depends on the MCP server implementation
+  - For **GitHub MCP server**, controls repository access with the following structure:
+    ```toml
+    [servers.github.guard_policies]
+    [servers.github.guard_policies.github]
+    owner = "github"                      # GitHub organization or user name
+    repos = ["gh-aw-mcpg", "gh-aw"]      # List of allowed repositories
+    ```
+    - **Meaning**: Restricts the GitHub MCP server to only access repositories `github/gh-aw-mcpg` and `github/gh-aw`
+    - Tools like `get_file_contents`, `search_code`, etc. will only work on these repositories
+    - Attempts to access other repositories will be denied by the guard policy
+  - For **other MCP servers** (Jira, WorkIQ, etc.), different policy schemas apply
+  - JSON format uses `"guard-policies"` (with hyphen), TOML uses `guard_policies` (with underscore)
+
 **Validation Rules:**
 
 - **JSON stdin format**:

config.example.toml

@@ -69,6 +69,14 @@ GITHUB_PERSONAL_ACCESS_TOKEN = ""  # Pass through from host
 # tools = ["*"]                    # Allow all tools (default)
 # tools = ["read_file", "list_files"]  # Allow specific tools only
 
+# Optional: Guard policies for access control at the MCP gateway level
+# The structure is server-specific. For GitHub MCP server, this controls repository access.
+# Example: Restrict access to specific GitHub organization and repositories
+# [servers.github.guard_policies]
+# [servers.github.guard_policies.github]
+# owner = "github"                 # GitHub organization or user
+# repos = ["gh-aw-mcpg", "gh-aw"]  # List of allowed repositories
+
 # Example 2: Memory MCP Server (stdio via Docker)
 [servers.memory]
 command = "docker"

internal/config/config_core.go

@@ -119,6 +119,10 @@ type ServerConfig struct {
 
 	// Registry is the URI to the installation location in an MCP registry (informational)
 	Registry string `toml:"registry" json:"registry,omitempty"`
+
+	// GuardPolicies holds guard policies for access control at the MCP gateway level.
+	// The structure is server-specific. For GitHub MCP server, see the GitHub guard policy schema.
+	GuardPolicies map[string]interface{} `toml:"guard_policies" json:"guard-policies,omitempty"`
 }
 
 // applyGatewayDefaults applies default values to a GatewayConfig if they are not set.

internal/config/config_stdin.go

@@ -68,6 +68,10 @@ type StdinServerConfig struct {
 	// Registry is the URI to the installation location in an MCP registry (informational)
 	Registry string `json:"registry,omitempty"`
 
+	// GuardPolicies holds guard policies for access control at the MCP gateway level.
+	// The structure is server-specific. For GitHub MCP server, see the GitHub guard policy schema.
+	GuardPolicies map[string]interface{} `json:"guard-policies,omitempty"`
+
 	// AdditionalProperties stores any extra fields for custom server types
 	// This allows custom schemas to define their own fields beyond the standard ones
 	AdditionalProperties map[string]interface{} `json:"-"`
@@ -107,6 +111,7 @@ func (s *StdinServerConfig) UnmarshalJSON(data []byte) error {
 		"headers":        true,
 		"tools":          true,
 		"registry":       true,
+		"guard-policies": true,
 	}
 
 	// Store additional properties (fields not in the struct)
@@ -270,11 +275,12 @@ func convertStdinServerConfig(name string, server *StdinServerConfig, customSche
 		logConfig.Printf("Configured HTTP MCP server: name=%s, url=%s", name, server.URL)
 		log.Printf("[CONFIG] Configured HTTP MCP server: %s -> %s", name, server.URL)
 		return &ServerConfig{
-			Type:     "http",
-			URL:      server.URL,
-			Headers:  server.Headers,
-			Tools:    server.Tools,
-			Registry: server.Registry,
+			Type:          "http",
+			URL:           server.URL,
+			Headers:       server.Headers,
+			Tools:         server.Tools,
+			Registry:      server.Registry,
+			GuardPolicies: server.GuardPolicies,
 		}, nil
 	}
 
@@ -332,12 +338,13 @@ func buildStdioServerConfig(name string, server *StdinServerConfig) *ServerConfi
 	logConfig.Printf("Configured stdio MCP server: name=%s, container=%s", name, server.Container)
 
 	return &ServerConfig{
-		Type:     "stdio",
-		Command:  "docker",
-		Args:     args,
-		Env:      make(map[string]string),
-		Tools:    server.Tools,
-		Registry: server.Registry,
+		Type:          "stdio",
+		Command:       "docker",
+		Args:          args,
+		Env:           make(map[string]string),
+		Tools:         server.Tools,
+		Registry:      server.Registry,
+		GuardPolicies: server.GuardPolicies,
 	}
 }
 

internal/config/config_test.go

@@ -166,8 +166,11 @@ func TestLoadFromStdin_UnsupportedType(t *testing.T) {
 	// Should fail validation for unsupported type
 	require.Error(t, err)
 
-	// Error should mention configuration error
-	assert.Contains(t, err.Error(), "Configuration error", "Expected configuration error")
+	// Error should mention configuration error or validation error
+	errorMsg := err.Error()
+	assert.True(t,
+		strings.Contains(errorMsg, "Configuration error") || strings.Contains(errorMsg, "Configuration validation error"),
+		"Expected configuration error or validation error, got: %s", errorMsg)
 
 	// Config should be nil on validation error
 	assert.Nil(t, cfg, "Config should be nil when validation fails")
@@ -1531,3 +1534,108 @@ registry = "https://api.mcp.github.com/v0/servers/github/github-mcp-server"
 
 	assert.Equal(t, "https://api.mcp.github.com/v0/servers/github/github-mcp-server", server.Registry, "Registry field not preserved in TOML config")
 }
+
+// TestLoadFromStdin_WithGuardPolicies tests that guard-policies field is correctly parsed from JSON stdin
+func TestLoadFromStdin_WithGuardPolicies(t *testing.T) {
+	jsonConfig := `{
+		"mcpServers": {
+			"github": {
+				"type": "stdio",
+				"container": "ghcr.io/github/github-mcp-server:latest",
+				"guard-policies": {
+					"github": {
+						"owner": "github",
+						"repos": ["gh-aw-mcpg", "gh-aw"]
+					}
+				}
+			},
+			"http-server": {
+				"type": "http",
+				"url": "https://example.com/mcp",
+				"guard-policies": {
+					"network": {
+						"allow": ["api.example.com"]
+					}
+				}
+			}
+		},
+		"gateway": {
+			"port": 8080,
+			"domain": "localhost",
+			"apiKey": "test-key"
+		}
+	}`
+
+	// Mock stdin
+	r, w, _ := os.Pipe()
+	oldStdin := os.Stdin
+	os.Stdin = r
+	go func() {
+		w.Write([]byte(jsonConfig))
+		w.Close()
+	}()
+
+	cfg, err := LoadFromStdin()
+	os.Stdin = oldStdin
+
+	require.NoError(t, err, "LoadFromStdin() failed")
+	require.NotNil(t, cfg, "Config should not be nil")
+
+	// Test stdio server with guard policies
+	githubServer, ok := cfg.Servers["github"]
+	require.True(t, ok, "Server 'github' not found")
+	require.NotNil(t, githubServer.GuardPolicies, "GuardPolicies should not be nil")
+
+	githubPolicy, ok := githubServer.GuardPolicies["github"]
+	require.True(t, ok, "GitHub policy not found in guard-policies")
+	githubPolicyMap, ok := githubPolicy.(map[string]interface{})
+	require.True(t, ok, "GitHub policy should be a map")
+	assert.Equal(t, "github", githubPolicyMap["owner"], "Owner field mismatch")
+
+	// Test HTTP server with guard policies
+	httpServer, ok := cfg.Servers["http-server"]
+	require.True(t, ok, "Server 'http-server' not found")
+	require.NotNil(t, httpServer.GuardPolicies, "GuardPolicies should not be nil for HTTP server")
+
+	networkPolicy, ok := httpServer.GuardPolicies["network"]
+	require.True(t, ok, "Network policy not found in guard-policies")
+	require.NotNil(t, networkPolicy, "Network policy should not be nil")
+}
+
+// TestLoadFromFile_WithGuardPolicies tests that guard_policies field is correctly parsed from TOML
+func TestLoadFromFile_WithGuardPolicies(t *testing.T) {
+	tmpDir := t.TempDir()
+	tmpFile := filepath.Join(tmpDir, "config.toml")
+
+	tomlContent := `
+[gateway]
+port = 8080
+api_key = "test-key"
+
+[servers.github]
+command = "docker"
+args = ["run", "--rm", "-i", "ghcr.io/github/github-mcp-server:latest"]
+
+[servers.github.guard_policies]
+[servers.github.guard_policies.github]
+owner = "github"
+repos = ["gh-aw-mcpg", "gh-aw"]
+`
+
+	err := os.WriteFile(tmpFile, []byte(tomlContent), 0644)
+	require.NoError(t, err, "Failed to write temp TOML file")
+
+	cfg, err := LoadFromFile(tmpFile)
+	require.NoError(t, err, "LoadFromFile() failed")
+	require.NotNil(t, cfg, "Config should not be nil")
+
+	server, ok := cfg.Servers["github"]
+	require.True(t, ok, "Server 'github' not found")
+	require.NotNil(t, server.GuardPolicies, "GuardPolicies should not be nil")
+
+	githubPolicy, ok := server.GuardPolicies["github"]
+	require.True(t, ok, "GitHub policy not found in guard_policies")
+	githubPolicyMap, ok := githubPolicy.(map[string]interface{})
+	require.True(t, ok, "GitHub policy should be a map")
+	assert.Equal(t, "github", githubPolicyMap["owner"], "Owner field mismatch in TOML config")
+}

internal/config/validation_schema.go

@@ -30,20 +30,19 @@ var (
 	// This URL points to the source of truth for the MCP Gateway configuration schema.
 	//
 	// Schema Version Pinning:
-	// The schema is pinned to a specific gh-aw version (v0.41.1) for build reproducibility.
-	// This ensures predictable builds and prevents unexpected breaking changes from upstream
-	// schema updates.
+	// The schema is fetched from the main branch to get the latest version with guard-policies support.
+	// This ensures the gateway supports the latest configuration features including guard policies.
 	//
-	// To update the schema version:
+	// To update to a specific pinned version:
 	//   1. Check the latest gh-aw release: https://github.com/github/gh-aw/releases
-	//   2. Update the version tag in the URL below
+	//   2. Update the URL below to use a version tag instead of main
 	//   3. Run tests to ensure compatibility: make test
-	//   4. Update this comment with the new version number
+	//   4. Update this comment with the version number
 	//
-	// Current schema version: v0.41.1 (February 2026)
+	// Current schema version: main (latest with guard-policies support)
 	//
 	// Alternative: Embed the schema using go:embed directive for zero network dependency.
-	schemaURL = "https://raw.githubusercontent.com/github/gh-aw/v0.41.1/docs/public/schemas/mcp-gateway-config.schema.json"
+	schemaURL = "https://raw.githubusercontent.com/github/gh-aw/main/pkg/workflow/schemas/mcp-gateway-config.schema.json"
 
 	// Schema caching to avoid recompiling the JSON schema on every validation
 	// This improves performance by compiling the schema once and reusing it