docs: Enhance MCP documentation and validation for network permissions

Signed-off-by: Jiaxiao Zhou <duibao55328@gmail.com>

Author: Mossaka

docs/mcps.md

@@ -212,15 +212,22 @@ tools:
 
 Enforcement in compiled workflows:
 
-- A Squid proxy is generated and pinned to a dedicated Docker network for each proxy‑enabled MCP server.
+- A [Squid proxy](https://www.squid-cache.org/) is generated and pinned to a dedicated Docker network for each proxy‑enabled MCP server.
 - The MCP container is configured with `HTTP_PROXY`/`HTTPS_PROXY` to point at Squid; iptables rules only allow egress to the proxy.
 - The proxy is seeded with an `allowed_domains.txt` built from your `allowed` list; requests to other domains are blocked.
 
 Notes:
 
-- Applies to stdio MCP servers that specify a `container`. Non‑container stdio and remote `type: http` servers do not use this control (at the moment)
+- **Only applies to stdio MCP servers with `container`** - Non‑container stdio and `type: http` servers will cause compilation errors
 - Use bare domains without scheme; list each domain you intend to permit.
 
+### Validation Rules
+
+The compiler enforces these network permission rules:
+
+- ❌ **HTTP servers**: `network egress permissions do not apply to remote 'type: http' servers`
+- ❌ **Non-container stdio**: `network egress permissions only apply to stdio MCP servers that specify a 'container'`  
+- ✅ **Container stdio**: Network permissions work correctly
 
 ## Debugging and Troubleshooting
 

docs/security-notes.md

@@ -190,7 +190,7 @@ Enforcement details:
 
 - Compiler generates a per‑tool Squid proxy and Docker network; MCP egress is forced through the proxy via iptables.
 - Only listed domains are reachable; all others are denied at the network layer.
-- Applies to `mcp.container` stdio servers. Non‑container stdio and `type: http` servers are not governed by this control.
+- Applies to `mcp.container` stdio servers. Non‑container stdio and `type: http` servers are not supported and will cause compilation errors.
 
 Operational guidance:
 

pkg/workflow/mcp-config.go

@@ -371,7 +371,7 @@ func ValidateMCPConfigs(tools map[string]any) error {
 				}
 
 				// Validate MCP configuration requirements (before transformation)
-				if err := validateMCPRequirements(toolName, mcpConfig); err != nil {
+				if err := validateMCPRequirements(toolName, mcpConfig, config); err != nil {
 					return err
 				}
 			}
@@ -471,7 +471,7 @@ func hasNetworkPermissions(toolConfig map[string]any) (bool, []string) {
 }
 
 // validateMCPRequirements validates the specific requirements for MCP configuration
-func validateMCPRequirements(toolName string, mcpConfig map[string]any) error {
+func validateMCPRequirements(toolName string, mcpConfig map[string]any, toolConfig map[string]any) error {
 	// Validate 'type' property
 	mcpType, hasType := mcpConfig["type"]
 	if err := validateStringProperty(toolName, "type", mcpType, hasType); err != nil {
@@ -489,6 +489,25 @@ func validateMCPRequirements(toolName string, mcpConfig map[string]any) error {
 		return fmt.Errorf("tool '%s' mcp configuration 'type' value must be one of: stdio, http", toolName)
 	}
 
+	// Validate network permissions usage first
+	hasNetPerms, _ := hasNetworkPermissions(toolConfig)
+	if !hasNetPerms {
+		// Also check if permissions are nested in the mcp config itself
+		hasNetPerms, _ = hasNetworkPermissions(map[string]any{"mcp": mcpConfig})
+	}
+	if hasNetPerms {
+		switch typeStr {
+		case "http":
+			return fmt.Errorf("tool '%s' has network permissions configured, but network egress permissions do not apply to remote 'type: http' servers", toolName)
+		case "stdio":
+			// Network permissions only apply to stdio servers with container
+			_, hasContainer := mcpConfig["container"]
+			if !hasContainer {
+				return fmt.Errorf("tool '%s' has network permissions configured, but network egress permissions only apply to stdio MCP servers that specify a 'container'", toolName)
+			}
+		}
+	}
+
 	// Validate type-specific requirements
 	switch typeStr {
 	case "http":

pkg/workflow/mcp_json_test.go

@@ -320,6 +320,81 @@ func TestValidateMCPConfigs(t *testing.T) {
 			wantErr: true,
 			errMsg:  "missing property 'url'",
 		},
+		{
+			name: "network permissions with HTTP type should fail",
+			tools: map[string]any{
+				"httpWithNetPerms": map[string]any{
+					"mcp": map[string]any{
+						"type": "http",
+						"url":  "https://example.com",
+					},
+					"permissions": map[string]any{
+						"network": map[string]any{
+							"allowed": []any{"example.com"},
+						},
+					},
+					"allowed": []any{"tool1"},
+				},
+			},
+			wantErr: true,
+			errMsg:  "network egress permissions do not apply to remote 'type: http' servers",
+		},
+		{
+			name: "network permissions with stdio non-container should fail",
+			tools: map[string]any{
+				"stdioNonContainerWithNetPerms": map[string]any{
+					"mcp": map[string]any{
+						"type":    "stdio",
+						"command": "python",
+					},
+					"permissions": map[string]any{
+						"network": map[string]any{
+							"allowed": []any{"example.com"},
+						},
+					},
+					"allowed": []any{"tool1"},
+				},
+			},
+			wantErr: true,
+			errMsg:  "network egress permissions only apply to stdio MCP servers that specify a 'container'",
+		},
+		{
+			name: "network permissions with stdio container should pass",
+			tools: map[string]any{
+				"stdioContainerWithNetPerms": map[string]any{
+					"mcp": map[string]any{
+						"type":      "stdio",
+						"container": "mcp/fetch",
+					},
+					"permissions": map[string]any{
+						"network": map[string]any{
+							"allowed": []any{"example.com"},
+						},
+					},
+					"allowed": []any{"tool1"},
+				},
+			},
+			wantErr: false,
+		},
+		{
+			name: "network permissions in mcp section with HTTP type should fail",
+			tools: map[string]any{
+				"httpWithMcpNetPerms": map[string]any{
+					"mcp": map[string]any{
+						"type": "http",
+						"url":  "https://example.com",
+						"permissions": map[string]any{
+							"network": map[string]any{
+								"allowed": []any{"example.com"},
+							},
+						},
+					},
+					"allowed": []any{"tool1"},
+				},
+			},
+			wantErr: true,
+			errMsg:  "network egress permissions do not apply to remote 'type: http' servers",
+		},
 	}
 
 	for _, tt := range tests {