Configuration
/
Custom domain setup
Last updated

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


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


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.


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


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


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


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


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:

# 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:
    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:
    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