Connect a Domain for AI Agents

AI agents can already generate a codebase, provision infrastructure, and deploy a working app in minutes. Then they stall at the last step: connecting a real custom domain. This repository explains how domain registration, DNS configuration, control verification, and TLS issuance actually work, and shows the practical ways to let an agent finish that step programmatically. It is maintained by CustomDomain, which operates a hosted MCP server and a REST API built for exactly this workflow.

What this repository is

A field guide for people building agent products that ship websites and apps: site-generating agents, coding agents with a deploy step, and workflow agents that spin up landing pages, stores, and docs sites. It covers the problem space first (DNS, control proof, TLS, propagation), then the ways records can get into a customer's DNS zone, then the concrete implementation paths (widget, REST API, MCP tools). Deep dives live in docs/:

| Deep dive | What it covers | |---|---| | Agents that ship websites need domains | The agent-provisions-everything pattern and exactly where the domain step breaks it | | An MCP server for domains | The hosted MCP tool surface: the twelve tools, their arguments, and config snippets for Claude and Cursor | | Programmatic domain connection over REST | The full API flow end to end, real request and response shapes, failure handling, and an agent tool definition | | Security for agent-driven DNS | Scoped credentials, human approval points, and why agents should never hold registrar passwords |

The problem: agents ship everything except the domain

An agent that builds and deploys a site produces a preview URL on a platform subdomain. The user's next message is predictable: "make it live on acmebakery.com." At that moment the agent needs three things to happen in someone else's infrastructure: routing records written into a DNS zone it does not control, a demonstration that the user actually controls that zone, and a TLS certificate for the hostname. Then it has to wait for resolvers worldwide to return the new answers.

Humans already struggle here. The knowledge base of the Domain Connect project (published under CC0 1.0) reports that approximately 50% of users who attempt manual DNS configuration fail and abandon the process, and documents one major productivity suite whose email onboarding requires 7 to 15 hand-created records and 16 help sites, 10 of them registrar-specific. Those users had already paid. They simply could not translate "add a CNAME" into the right clicks at their particular provider.

For an agent the failure mode is worse, because every workaround available to a human is unavailable or dangerous for an agent:

• No hands. The registrar's DNS panel is a browser UI, often behind 2FA. Driving it with browser automation is brittle and, with real registrar credentials in the loop, genuinely risky.
• No safe credentials. The obvious shortcut, "just give the agent my registrar password," hands an autonomous system full control of the zone, email routing, transfer locks, and billing. Don't do this.
• No durable state. DNS propagation can outlive an agent session. Without a resumable, queryable state machine, the agent cannot pick up where it left off.
• No feedback. A human squints at a help article and retries. An agent needs deterministic statuses, explicit error codes, and webhooks or pollable endpoints.

The result is the autonomy cliff: a fully automated build pipeline that ends with "now open your registrar dashboard and paste these records." The rest of this README is about removing that cliff.

How domain connection actually works

Four mechanisms, in order. If you internalize these, every provider quirk becomes explainable.

1. Routing: DNS records point the name at your edge

A subdomain routes with a CNAME. A zone apex (the bare domain) cannot legally carry a CNAME alongside its other records, so it needs an A/AAAA record or a provider-specific ALIAS/ANAME that flattens to one:

; subdomain: CNAME to the platform edge
www.acmebakery.com.    3600  IN  CNAME  edge.customdomain.ai.

; apex: ALIAS/ANAME where the provider supports it, otherwise A
acmebakery.com.        3600  IN  A      203.0.113.10

CustomDomain's record set carries a provider-agnostic APEXCNAME type for this case, realized to the host's native ALIAS, ANAME, or flattened CNAME on write, and rendered as ALIAS in manual instructions. Providers that cannot host any CNAME-like record at the zone root are caught before a connection is created: POST /v1/domains:check returns apex_supported: false with an apex_message, rather than letting the connection fail at apply time.

Getting these exactly right, at the right provider, in the right zone, is the step that generates most support tickets. See the plain-language walkthrough at How to set up a custom domain and the custom domain vs subdomain glossary entry for why a platform subdomain is not a substitute.

2. Proof: the rail is the proof

Before a platform serves traffic for a hostname, it must establish that the requesting user controls that DNS zone. Many platforms do this with a separate scoped TXT challenge. CustomDomain does not, and it is worth understanding why, because it changes what an agent has to orchestrate.

Control is proven by whatever mechanism wrote the records:

• An OAuth authorization at the DNS provider. Only someone who can log into the zone can grant it.
• A one-click template apply at a Domain Connect provider. Same argument, provider-hosted.
• A scoped provider API token the customer created and supplied.
• In the manual flow, the records appearing in public DNS is itself the proof. Nobody else can put a CNAME on the customer's hostname.

The practical consequence for an agent: there is no verification step to poll separately, and no _challenge record to relay to a user. There is one record set, and either it resolves or it does not. If you are reading older copy of ours that describes a TXT ownership challenge, that copy was wrong. See Connections for the authoritative description.

3. Security: TLS issuance and renewal

Once the records resolve, a certificate is issued for the hostname from a publicly trusted certificate authority and installed at a reverse-proxy edge that terminates TLS. On the hosted service, issuance happens on the next TLS handshake for that host, and renewal is scheduled automatically. Your platform never generates a CSR, never stores the private key, and never wakes up to an expired certificate. Hosts whose records do not resolve never reach the edge and so never get a certificate.

4. Waiting: propagation and TTLs

"Propagation" is not a push; it is caches expiring. Every resolver that previously looked up the name keeps its answer until the record's TTL runs out. Records written correctly on the first attempt, with sensible TTLs, resolve quickly. Records written wrong, then corrected, inherit the old TTL on the wrong answer, which is why manual setups "take 24 to 48 hours" in folklore and automated ones usually do not. When records are written through provider authorization, a domain is typically live in about 30 seconds. A background poller re-resolves every pending and propagating connection on a one-minute interval, with value checking: a CNAME must resolve to the expected target, an A or AAAA must contain the exact address.

Three ways to get records into the customer's zone

Every domain connection product, and every homegrown flow, reduces to one of these. CustomDomain implements all of them across 63 catalogued DNS and registrar providers. 25 of the 63 have an automatic path; the remaining 38 use guided manual setup with automatic verification. The split below is the live census at GET https://api.customdomain.ai/v1/providers/census, counted 2026-08-19. See one-click DNS setup for the provider-level view.

| Method | Providers | How it works | User effort | Typical time to live | |---|---|---|---|---| | One-click provider authorization | 8 (6 OAuth into the provider, 2 provider-hosted Domain Connect) | The user approves a scoped change at their DNS provider; correct records are applied for them | One approval click | About 30 seconds | | API token | 17 | The user pastes a scoped DNS API token from their provider; records are written through the provider's API | Create and paste one token | Minutes | | Guided manual with automatic verification | 38 | The user is shown the exact records for their detected provider and a poller waits for them to resolve, then proceeds automatically | Copy and paste records | Minutes to hours, TTL dependent |

Be honest with yourself about that third row: it is 38 of 63, the largest group. The fallback chain is the point, not a footnote. Detection fingerprints the user's provider from the domain's existing DNS, offers the best available method, and degrades to guided manual for the long tail. The agent's job stays the same in all three cases: create the connection, surface the next required human action if there is one, and poll or subscribe until the status reaches live.

The connection state machine

An agent needs to branch on state, so here is the complete vocabulary. There are exactly four values.

| Status | Meaning | Agent's move | |---|---|---| | pending | Created; records not yet written or not yet observed | Surface the next human action if the chosen rail needs one | | propagating | Records were written by a rail and are being checked against public DNS | Wait. Poll, or subscribe to connection.live | | live | Every desired record resolves to its intended value; the edge serves TLS for the host | Report success, store the connection id | | failed | Records never appeared inside the window | Read error_code, surface the concrete fix, then POST /v1/connections/{id}:recheck |

The failure windows are asymmetric on purpose: 24 hours from propagating on an automatic rail (a write that succeeded should resolve quickly), and 72 hours from pending on a manual connection, which is long enough for a human to get around to it. A failed connection carries error_code and error_message. The codes an agent will actually see include propagation_timeout (records never resolved), setup_incomplete (manual records were never added), apex_not_supported (the provider cannot host a CNAME-like record at the zone root), domain_already_connected, and dns_write_failed. Both fields clear automatically when the connection next verifies, and :recheck on a failed connection re-enters it into verification with the timeout clock re-based, so a retry does not immediately re-fail.

Because the connection is a durable resource and POST /v1/connections is idempotent per application plus domain, a connection created in one agent session is resumed from any later session with a single GET, or by simply re-posting the same domain.

Implementation paths: widget, API, or MCP

| Path | Best for | Integration shape | |---|---|---| | Connect widget and SDK | Agent products with a web UI where the end user completes the connection themselves | Embed a prebuilt flow; the widget handles provider detection,