Tencent/WeKnora · error

MCP service URL is required for OAuth

Error message

MCP service URL is required for OAuth

What it means

A synchronous validation error raised by OAuthManager.newHandler when the MCP service record has no URL. OAuth flows need a server endpoint to discover metadata and exchange tokens, so a nil/empty service.URL makes OAuth impossible. StartAuthorization and CompleteAuthorization both route through newHandler.

Source

Thrown at internal/mcp/oauth_manager.go:54

// in which case in-flight authorization states are kept in memory.
func NewOAuthManager(
	repo interfaces.MCPOAuthRepository,
	serviceRepo interfaces.MCPServiceRepository,
	rdb *redis.Client,
) *OAuthManager {
	return &OAuthManager{
		repo:        repo,
		serviceRepo: serviceRepo,
		states:      newOAuthStateStore(rdb),
	}
}

// newHandler builds an OAuth handler bound to a service + per-principal token store.
func (m *OAuthManager) newHandler(
	ctx context.Context, service *types.MCPService, tenantID uint64, principal types.Principal, redirectURI string,
) (*transport.OAuthHandler, error) {
	if service.URL == nil || *service.URL == "" {
		return nil, fmt.Errorf("MCP service URL is required for OAuth")
	}
	if err := ValidateServiceOutboundURLs(service); err != nil {
		return nil, err
	}
	httpCfg := secutils.DefaultSSRFSafeHTTPClientConfig()
	httpCfg.Timeout = 30 * time.Second
	cfg := transport.OAuthConfig{
		RedirectURI:           redirectURI,
		Scopes:                service.AuthConfig.Scopes,
		TokenStore:            newDBTokenStore(m.repo, tenantID, principal, service.ID),
		PKCEEnabled:           true,
		AuthServerMetadataURL: service.AuthConfig.AuthServerMetadataURL,
		HTTPClient:            secutils.NewSSRFSafeHTTPClient(httpCfg),
	}
	if existing, err := m.repo.GetClient(ctx, tenantID, service.ID); err == nil && existing != nil {
		cfg.ClientID = existing.ClientID
		cfg.ClientSecret = existing.ClientSecret
	}

View on GitHub (pinned to 988cbb0330)

Solutions

1. Set the service URL before enabling OAuth (update the MCP service record with a valid https:// URL)
2. Add a pre-save validation on service creation requiring URL when AuthConfig is OAuth
3. Query the DB for services with NULL/empty url and backfill them
4. Fix the API caller to pass the fully populated service object

Example fix

// before
svc.AuthConfig = types.NewOAuthConfig()
manager.StartAuthorizationForService(ctx, svc, tenant, principal, redirect, "")
// after
if svc.URL == nil || *svc.URL == "" {
    return fmt.Errorf("service %d needs a URL before OAuth setup", svc.ID)
}
manager.StartAuthorizationForService(ctx, svc, tenant, principal, redirect, "")

func oauthReady(svc *types.MCPService) error {
    if svc == nil { return fmt.Errorf("service is nil") }
    if !svc.AuthConfig.IsOAuth() { return fmt.Errorf("service %s is not OAuth", svc.ID) }
    if svc.URL == nil || *svc.URL == "" { return fmt.Errorf("service %s has no URL", svc.ID) }
    return nil
}

func hasServiceURL(svc *types.MCPService) bool {
    return svc != nil && svc.URL != nil && *svc.URL != ""
}

if err := oauthReady(svc); err != nil { return err }
if _, _, err := mgr.StartAuthorizationForService(ctx, svc, tenantID, principal, redirect, ""); err != nil {
    if strings.Contains(err.Error(), "URL is required") { return fmt.Errorf("misconfigured service %s: %w", svc.ID, err) }
    return err
}

When it happens

Trigger: Calling StartAuthorization/StartAuthorizationForService/CompleteAuthorization with a types.MCPService whose URL field is nil or the empty string.

Common situations: Service created via import or script without a URL; URL field cleared during an update; config file omitted the service endpoint; migration left legacy rows with NULL url.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• MCP service %s does not use OAuth
• invalid sandbox type
• timeout cannot be negative
• memory limit cannot be negative
• CPU limit cannot be negative

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