Tencent/WeKnora · error

MCP service URL failed SSRF validation: %w

Error message

MCP service URL failed SSRF validation: %w

What it means

ValidateServiceOutboundURLs in internal/mcp/security.go:23 wraps secutils.ValidateURLForSSRF when an MCP service's URL fails SSRF checks. The server refuses to persist or connect to an MCP service whose endpoint could be used for server-side request forgery (private IPs, localhost, non-HTTP schemes, unresolved DNS). The wrapped inner error describes the exact reason.

Source

Thrown at internal/mcp/security.go:23

	"strings"

	"github.com/Tencent/WeKnora/internal/types"
	secutils "github.com/Tencent/WeKnora/internal/utils"
)

// ValidateServiceOutboundURLs validates every URL that the MCP transport or
// OAuth discovery flow may contact. It is intentionally called both at
// persistence boundaries and immediately before client construction so stale
// or imported rows cannot bypass the current SSRF policy.
func ValidateServiceOutboundURLs(service *types.MCPService) error {
	if service == nil {
		return fmt.Errorf("MCP service is required")
	}
	if service.URL != nil {
		serviceURL := strings.TrimSpace(*service.URL)
		if serviceURL != "" {
			if err := secutils.ValidateURLForSSRF(serviceURL); err != nil {
				return fmt.Errorf("MCP service URL failed SSRF validation: %w", err)
			}
		}
	}
	if service.AuthConfig != nil {
		metadataURL := strings.TrimSpace(service.AuthConfig.AuthServerMetadataURL)
		if metadataURL != "" {
			if err := secutils.ValidateURLForSSRF(metadataURL); err != nil {
				return fmt.Errorf("MCP OAuth metadata URL failed SSRF validation: %w", err)
			}
		}
	}
	return nil
}

View on GitHub (pinned to 988cbb0330)

Solutions

1. Change the MCP service URL to a publicly resolvable http/https endpoint.
2. If the host is legitimately internal, add its hostname to the SSRF_WHITELIST environment/config so IsSSRFWhitelisted skips the private-IP checks.
3. Read the wrapped %w error for the specific reason (invalid scheme, no hostname, SSRF validation failed) and fix accordingly.
4. Ensure the URL includes a hostname and uses http or https.

Example fix

// before
svc := &types.MCPService{URL: strPtr("http://localhost:8080/sse")}
err := mcp.ValidateServiceOutboundURLs(svc) // fails SSRF validation
// after
svc := &types.MCPService{URL: strPtr("https://mcp.example.com/sse")}
// or add 'localhost' to SSRF_WHITELIST for trusted internal deployments
err := mcp.ValidateServiceOutboundURLs(svc) // nil

if err := secutils.ValidateURLForSSRF(strings.TrimSpace(*service.URL)); err != nil {
    // refuse before calling CreateMCPService
    return fmt.Errorf("unacceptable MCP URL: %w", err)
}

func isPublicHTTPURL(raw string) bool {
    u, err := url.Parse(raw)
    return err == nil && (u.Scheme == "http" || u.Scheme == "https") && u.Hostname() != ""
}

When it happens

Trigger: Calling CreateMCPService, UpdateMCPService, NewMCPClient, or newHandler with a service whose *service.URL (after trimming) is non-empty and fails ValidateURLForSSRF — e.g. URL points to 127.0.0.1, 10.x/192.168.x metadata IPs, uses file:// or other non-http(s) schemes, or has no hostname.

Common situations: Registering a local dev MCP server (http://localhost:8080) in a deployed environment; pointing the service at an internal Kubernetes service or cloud metadata endpoint; pasting an SSE endpoint with an unsupported scheme; missing SSRF_WHITELIST entries for legitimate internal hosts.

Related errors

• %s failed SSRF validation: %w
• MinerU URL blocked by SSRF check: %v
• MCP service is required
• MCP OAuth metadata URL failed SSRF validation: %w
• argument %d contains null bytes

AI-assisted analysis of Tencent/WeKnora@988cbb0330 (2026-09-02). Data as JSON: /api/errors/aa0a38e9650fcac8. Report an issue: GitHub.