Domain lifecycle

Tandem is a domain registrar as well as a host, so an agent can take a domain from “does this exist?” all the way to renewal — entirely over MCP. This guide covers the registrar lifecycle: check → purchase → attach → renew / auto-renew / transfer. For editing zone records, see Managing DNS records; for the mechanics of pointing a hostname at a service, see Custom domains and DNS.

Every cost-bearing action here runs through the org’s payment + approval policy and requires the org to pass the deploy gate (billing + recovery verified).

Ownership: the customer is the registrant

Domains registered through Tandem are registered in the customer’s own name — the org’s domain owner contact is the registrant of record, so the customer, not Tandem, legally owns their domains.

• Set it once, before the first purchase or transfer: set_domain_owner_contact (legal name, postal address, email, phone). Without it, purchase_domain/transfer_domain fail with domain_owner_contact_required.
• One-time email verification (ICANN): on first use of a contact, the registrar emails a verification link (sender donotreply@name-services.com) to the contact address. It must be clicked within 15 days or the registry suspends the domain — site and email on it go offline until verified. Tandem tracks the state and emails reminders automatically; once a contact is verified, later registrations under it need no new click.
• Check state: get_domain_ownership shows each domain’s status (verified / unverified / pending_suspension / suspended) and the deadline. purchase_domain’s response also carries ownershipVerification — when it says unverified, relay the “click the verification email” instruction to the owner immediately.
• Lost the email / domain suspended? resend_domain_verification re-sends it; a suspended domain is typically restored within minutes of the owner clicking the link. No support ticket needed.

The approval branch

purchase_domain, renew_domain, and transfer_domain all charge money, so each returns one of two shapes:

• Org owner → runs synchronously (status='registered' / 'renewed' / 'transferring').
• Non-owner → returns status='awaiting_owner_approval' with an approvalUrl the owner clicks to authorize; the action then completes automatically.

Both branches include costCents + currency so you can surface the price before or after. All three need the manage action.

Check availability

{ "name": "check_domain_availability", "arguments": { "stem": "acme" } }

Pass an explicit hostnames[] (max 30) or a stem to fan out across the default TLD set (com, io, ai, dev, app, co). Read-only — no charge, no order. Returns { results: [{ hostname, available, costCents, currency }] }. Use it to quote a price before purchasing.

Purchase

{ "name": "purchase_domain",
  "arguments": { "organizationId": "…", "hostname": "acme.dev", "serviceId": "…" } }

Registers the domain via the platform registrar and attaches it to the given service. Requires a paid org. purchase_domain only attaches the exact hostname it bought — to attach a subdomain or an already-owned domain, use attach_domain (see below).

Attach an already-owned or external domain

{ "name": "attach_domain", "arguments": { "serviceId": "…", "hostname": "api.acme.dev" } }

Attach classifies by live nameservers, not just registration. The 2×2 matrix:

• Cells 1 & 2 (NS is Tandem): The A record publishes automatically. In cell 2 (the “Parker” case — NS delegated to Tandem before attach), the zone is adopted and activated in one call.
• Cell 3 (external, NS elsewhere): Returns dnsAutoPublished=false with A-record instructions for the user’s DNS provider. Consider add_external_domain first if you want Tandem to host DNS.
• Cell 4 (registered here, NS elsewhere): Returns canRestoreNameservers=true. The domain was registered through Tandem but NS was changed. Call restore_domain_nameservers to switch back and re-enable auto-publishing. Tandem-hosted email DNS is also dark until NS returns.

Needs manage + developer.

Renew

{ "name": "renew_domain", "arguments": { "organizationId": "…", "hostname": "acme.dev" } }

Renews a Tandem-registered domain for one more year. Identify it by domainOrderId (from the portal’s domain list) or hostname. Needs manage + developer.

Auto-renew

{ "name": "set_domain_auto_renew",
  "arguments": { "organizationId": "…", "hostname": "acme.dev", "autoRenew": true } }

Flips automatic renewal on or off. When on, the daily sweep renews before expiry (each renewal still runs through the approval policy — small price drift auto-approves, larger jumps prompt an owner). When off, the domain lapses at expiry unless renewed manually. This only flips the flag — no charge, so no deploy gate applies. Needs manage + developer.

Restore Tandem nameservers

{ "name": "restore_domain_nameservers",
  "arguments": { "organizationId": "…", "hostname": "acme.dev" } }

If a Tandem-registered domain’s NS was changed to another provider (e.g., moved DNS to Cloudflare), this resets the registry’s NS back to Tandem (ns1-4.launchtandem.com). After DNS propagates (minutes to hours), attach_domain auto-publishes again and Tandem-hosted email DNS goes live. Only works for domains this org registered or transferred in. Needs manage + developer.

Transfer in

{ "name": "transfer_domain",
  "arguments": { "organizationId": "…", "hostname": "acme.com", "authCode": "…" } }

Transfers a domain registered elsewhere into Tandem, charging one year up front. Provide the EPP/auth code from the current registrar (optionally projectId/serviceId). Owner runs synchronously (status='transferring' with a transferOrderId); non-owner gets the approval branch. Completion at the registry typically takes a few days — poll status in the portal. Needs manage + developer.