Skip to main content

Connect Your Custom Domain

Setting up a custom domain allows you to use your own hostname (like api.yourdomain.com) instead of the default server URL. This guide walks you through the process of adding and verifying your custom domain.

Before You Start​

Before configuring your custom domain, make sure you have:

  • Access to your domain's DNS management console
  • Administrative control over the domain you want to connect
  • An active MCP server that you want to connect the custom domain to
tip

Custom domains must be configured with your DNS provider and validated by the platform before they can be used.

Add Your Custom Domain​

  1. Navigate to your MCP server dashboard and locate the custom domain configuration section.

  2. Click "Connect Your Custom Hostname" to begin the setup process.

  3. Enter your desired hostname (e.g., mcp.yourdomain.com) in the hostname field.

  4. The system will generate the necessary DNS records for domain verification. You'll see both DNS and HTTP validation options.

Domain Verification Methods​

The platform supports two verification methods to prove domain ownership:

DNS verification uses DNS records to prove domain ownership. The system will provide you with specific records to add:

CNAME Record​

  • Type: CNAME
  • Name: your.sub.domain (your chosen hostname)
  • Value: fallback.liblab.io (the target server)

TXT Record​

  • Type: TXT
  • Name: _cf-custom-hostname.mcp.yourdomain.com
  • Value: A unique verification token (e.g., 02f69ba3-2b05-4ff1-8f39-eaace57a294e)

Method 2: HTTP Verification​

HTTP verification requires you to serve a specific file at a particular URL:

  • HTTP URL: http://mcp.yourdomain.com/.well-known/cf-custom-hostname-challenge/34a38697-2411-4322-ae3d-b97ab74bb201
  • HTTP Body: The verification token (02f69ba3-2b05-4ff1-8f39-eaace57a294e)

Configure DNS Records​

  1. Log in to your DNS provider's management console (such as your domain registrar, DNS hosting service, or CDN provider).

  2. Navigate to the DNS management section for your domain.

  3. Add the required DNS records as shown in the verification interface:

    Add the CNAME record:

    Type: CNAME
    Name: your.sub.domain
    Target: fallback.liblab.io
    TTL: Auto or 300 (5 minutes)

    Add the TXT record:

    Type: TXT  
    Name: _cf-custom-hostname.mcp.yourdomain.com
    Value: [your-verification-token]
    TTL: Auto or 300 (5 minutes)

  4. Save your DNS changes.

DNS Propagation

DNS changes might take several minutes to propagate globally. Most changes are effective within 5-10 minutes, but can take up to 24 hours in some cases.

Verify Your Domain​

  1. After adding the DNS records, return to the custom domain configuration interface.

  2. Click the "VERIFY" button to initiate the verification process.

  3. The system will check for the presence of your DNS records and validate domain ownership.

  4. Once verification is successful, you'll see a "VERIFIED" status with a checkmark icon.

Connect to Windsurf​

Once your custom domain is verified, you can use it to connect Windsurf to your MCP server:

  1. Open Windsurf and navigate to the MCP servers configuration.

  2. Click the MCP servers button (hammer icon), then click Configure.

  3. Click View raw config to open the mcp_config.json file.

  4. Update your MCP server configuration to use your custom domain:

    mcp_config.json
    {
      "mcpServers": {
        "your-api": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://mcp.yourdomain.com"
          ]
        }
      }
    }

  5. Click Refresh in the Manage plugins tab to connect using your custom domain.

Troubleshooting​

Verification Failed​

If domain verification fails, check the following:

  • DNS Records: Ensure both CNAME and TXT records are correctly added
  • Record Values: Verify that the record values exactly match those provided
  • DNS Propagation: Wait a few more minutes for DNS changes to propagate
  • Record Names: Double-check that record names are entered correctly, including any subdomains

Common DNS Issues​

CNAME Conflicts: If you encounter issues with CNAME records, ensure you're not trying to add both CNAME and TXT records for the same subdomain root. The verification TXT record uses a different subdomain prefix to avoid conflicts.

TTL Settings: Set TTL (Time To Live) values to 300 seconds (5 minutes) or lower for faster propagation during initial setup.

Getting Help​

If you continue experiencing issues:

  1. Verify your DNS provider supports both CNAME and TXT record types
  2. Check that you have the correct permissions to modify DNS records
  3. Contact your DNS provider's support if records aren't propagating
  4. Ensure there are no conflicting DNS records for the same hostname

Managing Custom Domains​

Updating Your Domain​

To change your custom domain, you'll need to:

  1. Delete the existing custom domain configuration
  2. Remove the old DNS records from your DNS provider
  3. Follow this guide again with your new domain

Removing a Custom Domain​

To remove a custom domain:

  1. Click the DELETE button next to your verified domain
  2. Remove the associated DNS records from your DNS provider
  3. Update your Windsurf configuration to use the default server URL

Next Steps​

After successfully connecting your custom domain:

  • Test your MCP server connection through Windsurf using natural language queries
  • Configure any necessary API authentication using environment variables
  • Monitor your custom domain's SSL certificate status and renewal

For more information about MCP servers and Windsurf integration:

Last updated on