> ## Documentation Index
> Fetch the complete documentation index at: https://docs.horizon.prefect.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom domains

> Serve a hosted MCP server from a subdomain you control with Horizon-managed DNS verification and TLS.

export const customDomainsPlans = "Enterprise";

A custom domain gives a hosted server a client-facing URL under a domain your
organization controls. Horizon keeps the deployment behind that URL and manages
the TLS certificate. Clients can then connect to
`https://mcp.example.com/mcp` instead of the default `fastmcp.app` URL.

<Note>
  Custom domains are available on {customDomainsPlans}. You need permission to
  edit the server and control of the subdomain's DNS records.
</Note>

A custom domain points to the same production serving target as the server's
default URL. Promotion and rollback change the artifact behind both URLs
together. Preview deployments cannot receive a custom domain, and a serving
target can have one custom domain at a time.

## Add a domain

<Steps>
  <Step title="Open domain settings">
    Open the hosted server, then select <b>Settings</b> and <b>Domains</b>.
    Select <b>Add domain</b>.
  </Step>

  <Step title="Choose the subdomain">
    Enter a fully qualified subdomain such as `mcp.example.com`. Horizon
    connects it to the production serving target and starts provisioning the
    domain and its TLS certificate.
  </Step>

  <Step title="Add DNS records">
    Copy both CNAME records shown by Horizon into your DNS provider. One record
    points the subdomain at Horizon. The other proves domain ownership so AWS
    Certificate Manager can issue the certificate.
  </Step>

  <Step title="Wait for verification">
    DNS changes can take time to propagate. Horizon checks the records while the
    domain shows <b>Verification needed</b>. Select <b>Refresh</b> after the
    records have propagated if the status has not updated.
  </Step>

  <Step title="Connect clients">
    When the status changes to <b>Valid configuration</b>, connect clients to
    `https://<your-domain>/mcp`. Authentication and authorization remain the
    same as on the default server URL.
  </Step>
</Steps>

## DNS records

Horizon displays the exact names and values to enter. Keep both records in place
while the domain is active because Horizon uses them for routing and certificate
validation.

| Record           | Purpose                                                            |
| ---------------- | ------------------------------------------------------------------ |
| Target CNAME     | Routes the chosen subdomain to Horizon.                            |
| Validation CNAME | Proves control of the domain for managed TLS issuance and renewal. |

### CAA records

CAA records restrict which certificate authorities can issue certificates.
Most domains need no CAA change. For example, AWS Certificate Manager (ACM) can
issue a certificate for `mcp.example.com` when `example.com` has no CAA records.

If `example.com` only allows another certificate authority, add
`CAA 0 issue "amazontrust.com"` alongside its existing CAA records. This lets ACM
issue and renew the custom domain's certificate. See the [AWS guide to CAA
errors](https://docs.aws.amazon.com/acm/latest/userguide/troubleshooting-caa.html)
for more information.

<Warning>
  Custom domains use CNAME records and Horizon-managed certificates. An A
  record, a customer-supplied certificate, or a wildcard domain cannot replace
  this setup.
</Warning>

## Domain states

| Status              | Meaning                                                        | Action                                                                                                        |
| ------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Setting up          | Horizon is creating the serving alias and certificate request. | Wait for the DNS records to appear.                                                                           |
| Verification needed | Horizon is waiting for the required DNS records.               | Add or correct the displayed records, then refresh.                                                           |
| Valid configuration | DNS and TLS are ready.                                         | Connect clients to the custom URL.                                                                            |
| Failed              | Provisioning or validation did not complete.                   | Review the displayed error. Retry recoverable errors or contact support for a certificate validation failure. |

An ACM certificate that reaches `Failed` cannot return to pending validation.
If the displayed error says that certificate validation failed, contact
[horizon-support@prefect.io](mailto:horizon-support@prefect.io) to restart the
setup. For other errors, correct the reported issue and select **Refresh**.

## Remove a domain

Removing a custom domain deletes its Horizon routing and managed certificate.
Requests to that domain stop working immediately. The default Horizon server URL
continues to route to the production deployment.

Remove the DNS records after Horizon has removed the domain. Update MCP clients
to another URL before removal so they do not lose access.

## Related docs

<CardGroup cols={2}>
  <Card title="Deployments" icon="cloud-arrow-up" href="/deployments">
    Understand the production serving target behind a custom domain.
  </Card>

  <Card title="Connect a client" icon="plug" href="/connect-a-client">
    Configure MCP clients with a server URL and credential.
  </Card>
</CardGroup>