# Custom domain setup Configure custom domains for your agent-ready applications to provide a branded experience for both authentication and MCP gateway access. ## Overview Frontegg allows you to configure custom domains in two key areas of your agent application: 1. **Authentication Domain** - Used for your authorization server federation URL and login flows 2. **MCP Gateway Domain** - Used for your MCP gateway URL endpoint Custom domains help you maintain brand consistency and provide a professional experience for your users. ## Prerequisites Before configuring custom domains, ensure you have: - Domain ownership and administrative access - DNS management access for your domain ## Authentication domain configuration The authentication custom domain is used for your authorization server federation URL and all authentication-related endpoints. ### Configuring your authentication domain To configure a custom domain for authentication, open the **Frontegg portal** and navigate to **[Portal] → [Configuration] → [Authentication configuration]**. ![custom-domain](/assets/auth-config.2a8ff80901339fe99d07f93655803945ef05e2cdba7f9413641e6b1a9f3c9cc4.80b3813c.png) br In the **Authentication configuration** section, locate the **Custom domain** field and click on **Configure**. In the popup dialog box, insert your desired domain name to generate the CNAME record you need for your DNS configuration. ![custom-domain](/assets/custom-domain-2.3d165690b8283d71746e1e78667a54e9e5030e1770d1f8f264e0f2fb4862d54d.42627d99.png) br Best practice A common practice is to use a subdomain as the custom domain. For example, if your app is hosted on `app.sample.com` and you have an existing A record for that domain, you cannot use `app.sample.com` as a custom domain on Frontegg. Instead, use a subdomain as the custom domain, like `auth.sample.com`. br After adding the CNAME to your DNS configuration, click the **Verify** button. If Frontegg is able to verify the CNAME record, you will see a success message. After a successful setup, you should also see your custom domain listed with a verified tag. Domain verification typically takes anywhere from a few minutes to a few hours. If you see a notification that Frontegg is unable to verify your custom domain, please double-check that you entered your CNAME correctly in your DNS provider and try again. ![custom-domain](/assets/custom-domain-3.41f91f525de01885290d3b6c260b2a3e8e0559ca33026b659cb1baf85d7d3d67.42627d99.png) br A `CNAME does not exist` error may appear if your domain failed validation, possibly due to a Certificate Authority Authorization (CAA) issue. This can usually be resolved by adding the appropriate CAA record to your DNS settings. ### What gets customized Once configured, your authentication domain will be used for: - **Authorization server federation URL**: Previously `[subdomain].frontegg.com`, now becomes `auth.yourdomain.com` - Login and authentication flows - OAuth/OIDC endpoints - User authentication sessions ### Default behavior If no custom domain is configured, the system displays "No domain configured" and uses the default Frontegg domain structure: `[subdomain].frontegg.com` ## MCP gateway URL configuration The MCP gateway custom domain is used for your Model Context Protocol gateway endpoint, which handles agent communication and tool execution. ### Configuring your MCP gateway domain To configure a custom domain for your MCP gateway, open the **Frontegg portal** and navigate to **[Portal] → [Settings] → [Basic Configuration]**. ![custom-domain](/assets/basic-config.ce325728a57b30b2c247188dc563ead5cabc00dd83796cca570894745a1837e4.80b3813c.png) br In the **Basic configuration** section, you'll see the **MCP gateway URL** field displaying your subdomain prefix (e.g., `dbx7b2vcyovztz0pzmqgp`) followed by `.mcp-gw.frontegg.com`. Below this, in the **Custom domain** section, click on **Configure**. In the popup dialog box, insert your desired domain name to generate the CNAME record you need for your DNS configuration. ![custom-domain](/assets/custom-domain-2.3d165690b8283d71746e1e78667a54e9e5030e1770d1f8f264e0f2fb4862d54d.42627d99.png) br Best practice Use a dedicated subdomain for your MCP gateway, such as `mcp.sample.com` or `gateway.sample.com`, to keep it separate from your authentication domain and maintain a clear separation of concerns. After adding the CNAME to your DNS configuration, click the **Verify** button. If Frontegg is able to verify the CNAME record, you will see a success message. After a successful setup, you should also see your custom domain listed with a verified tag. Domain verification typically takes anywhere from a few minutes to a few hours. If you see a notification that Frontegg is unable to verify your custom domain, please double-check that you entered your CNAME correctly in your DNS provider and try again. ![custom-domain](/assets/custom-domain-3.41f91f525de01885290d3b6c260b2a3e8e0559ca33026b659cb1baf85d7d3d67.42627d99.png) br A `CNAME does not exist` error may appear if your domain failed validation, possibly due to a Certificate Authority Authorization (CAA) issue. This can usually be resolved by adding the appropriate CAA record to your DNS settings. ### What gets customized Once configured, your MCP gateway domain will be used for: - Agent communication endpoints - Tool execution requests - MCP protocol interactions - Integration callbacks ### Default behavior If no custom domain is configured, the system displays "No domain configured" and uses the default MCP gateway structure: `[subdomain].mcp-gw.frontegg.com` ### DNS propagation DNS changes typically propagate within a few minutes to a few hours, though in rare cases it can take up to 24 hours. Frontegg will automatically provision SSL certificates once DNS is verified. You can verify DNS resolution using command-line tools: ```bash # Verify DNS resolution dig auth.yourdomain.com CNAME nslookup auth.yourdomain.com ``` ## Verification and testing ### Verify authentication domain 1. After DNS propagation, test your authentication domain: ```bash curl https://auth.yourdomain.com/.well-known/openid-configuration ``` 2. Verify that the authorization endpoints return the expected configuration ### Verify MCP gateway domain 1. Test your MCP gateway endpoint: ```bash curl https://mcp.yourdomain.com/health ``` 2. Ensure your agent applications can connect to the custom domain ## Best practices 1. **Use Subdomains**: Use dedicated subdomains (e.g., `auth.` and `mcp.`) rather than root domains 2. **Plan for Both**: Configure both authentication and MCP gateway domains for a consistent branded experience 3. **Test Before Production**: Verify both domains in a staging environment before updating production applications 4. **Monitor DNS**: Keep track of DNS record expiration and renewal dates 5. **Document Changes**: Maintain documentation of your custom domain configuration for your team 6. **SSL/TLS**: Frontegg automatically manages SSL certificates, but ensure your domain supports HTTPS ## Troubleshooting ### Domain not verifying **Issue**: Custom domain verification fails after adding DNS records **Solutions**: - Wait longer for DNS propagation (up to 24 hours in rare cases) - Verify CNAME record is correctly pointing to the Frontegg hostname - Check for conflicting A or CNAME records - Ensure there are no DNS caching issues: `dig +trace auth.yourdomain.com` ### SSL certificate errors **Issue**: SSL certificate warnings when accessing custom domain **Solutions**: - Allow time for Frontegg to provision the SSL certificate (up to 1 hour after verification) - Verify DNS records are correctly configured - Clear browser cache and try again - Contact Frontegg support if issues persist after 24 hours ### MCP gateway connection issues **Issue**: Agents cannot connect to custom MCP gateway domain **Solutions**: - Verify the MCP gateway URL in your application configuration - Test connectivity: `curl https://mcp.yourdomain.com/health` - Check firewall rules allow outbound connections to the custom domain - Verify API base URL and MCP gateway URL are both correctly configured ## Security considerations - **HTTPS Only**: All custom domains must use HTTPS (enforced by Frontegg) - **Certificate Management**: Frontegg automatically provisions and renews SSL/TLS certificates using Let's Encrypt - **Domain Validation**: Only verified domains can be used for authentication and MCP gateway endpoints ## Next steps - [Configure authentication settings](/agent-link/configuration/authentication/overview) with your custom domain - [Set up backend verification](/agent-link/configuration/backend-verification) for secure token validation - [Learn about agent applications](/agent-link/getting-started/quickstart)