Connect a domain with an AI assistant

Walk a merchant through a custom domain's whole life with the hosted MCP tools: add, setup, HTTPS, storefront, health, hosted DNS and removal.

A connected AI assistant can take a merchant through a custom domain's whole life with the hosted MCP server (https://api.tringify.com/mcp/store): choosing how to connect it, setting it up, HTTPS, assigning it to a storefront, keeping it healthy, hosting its DNS and removing it. The assistant never has to work out a DNS step itself: every domain the tools return says what to show and what to call next, in the merchant's language, exactly as Store Admin and the mobile app show it. The connection needs store:settings.domains:read to read and store:settings.domains:write to change domains; see Connect an AI assistant.

What every domain carries#

Field	What it is	What the assistant does with it
`badge`	`label` and `tone` (positive, neutral, warning, critical): the domain's status.	Show the label.
`role_label`	Primary address, country domain, redirects to the primary address, or not assigned.	Show it next to the domain.
`setup`	The step list: `steps` with `label`, `status` and `message`; `nameservers` to set or `records` to add with what public DNS shows; `last_checked` and `next_check`.	Show the current step and the nameservers or records to the merchant.
`next_action`	The single next step: `key`, `label`, `message`, `after`, and the `tool` and `arguments` to call. Absent when nothing is left to do.	Show `label` and `message`; call `tool` with `arguments` when the merchant is ready, or after `after` for a wait.
`issue`	What is wrong after the merchant's part was done: `key`, `title`, `message`, `fix`, `since` (RFC 3339 in store time), and `deadline` for a DNS warning.	Show the title, message and fix as given.
`actions`	What the domain allows now: check, assign_storefront, unassign, set_primary, clear_primary, set_country, clear_country, manage_dns, remove.	Offer only these.

1. Add the domain#

Ask which address to connect, then call connect_domain with action: discover. options explains each way to connect that address in plain words; chosen is the recommendation. Show each option's label and description (and unavailable_reason for one that doesn't suit the address) and let the merchant choose.

json

{
  "tool": "connect_domain",
  "arguments": {
    "action": "discover",
    "domain": "shop.example.com"
  }
}

json

{
  "domain": "shop.example.com",
  "domain_display": "shop.example.com",
  "chosen": "external",
  "options": [
    {
      "mode": "managed",
      "label": "Change nameservers to Tringify",
      "available": false,
      "unavailable_reason": "Only a root domain such as example.com can move its nameservers. …"
    },
    {
      "mode": "external",
      "label": "Keep my DNS host and add two records",
      "description": "shop.example.com's DNS stays at Cloudflare. You add a TXT record that proves you own it and a CNAME record that points it to Tringify. …",
      "available": true,
      "recommended": true
    }
  ]
}

Then call create_domain with the chosen dns_management. Refusals are backend messages to relay as given: DOMAIN_LIMIT_REACHED (the plan's maximum), DOMAIN_INVALID_FORMAT, DOMAIN_ALREADY_IN_USE, and DOMAIN_CLAIM_REQUIRED when another store added the domain but never finished: its message names a TXT record to publish before adding again. Internationalized names can be sent in Unicode; domain is the ASCII form Tringify stores and domain_display the form to show.

2. Set it up#

The new domain's next_action says what the merchant does at their registrar or DNS host. Show next_action.message with setup.nameservers (nameservers path) or setup.records (records path, each with its host, type, value and what public DNS shows now).

json

{
  "badge": {
    "label": "Action needed",
    "tone": "warning"
  },
  "next_action": {
    "key": "change_nameservers",
    "label": "Change nameservers at your registrar",
    "message": "Sign in where you bought example.com (for example Hostinger, GoDaddy or Namecheap), open its nameserver settings, choose custom nameservers and replace every entry with the nameservers below.",
    "tool": "verify_domain",
    "arguments": {
      "domain_id": "3f0d9a8e-6a7b-4c2d-9e1f-5a4b3c2d1e0f"
    },
    "after": "Next automatic check: Oct 27, 2026, 9:42 AM"
  },
  "setup": {
    "path": "nameservers",
    "state": "action_required",
    "nameservers": [
      "ada.ns.cloudflare.com",
      "bob.ns.cloudflare.com"
    ]
  }
}

When the merchant says they made the change, call next_action.tool (verify_domain). It runs the next step at once and never fails the domain while DNS is still spreading; its message says what Tringify sees now. The steps then advance by themselves: on the nameservers path Cloudflare activates the zone, Tringify writes the records and verifies ownership; on the records path Tringify finds the records and verifies ownership. While nothing is left for the merchant, next_action.key is wait with tool get_domain. If connect_domain (action: apply) returns apply_url, the merchant opens it in their browser to approve the records at their DNS host; never open or fetch it yourself.

3. HTTPS#

After ownership is verified Cloudflare issues the certificate, usually within minutes. When something blocks it, issue names the cause and next_action is fix_dns:

certificate_caa: a CAA record doesn't allow the certificate authorities Tringify uses. Fix: allow letsencrypt.org and pki.goog, or remove the CAA records.
certificate_proxied_elsewhere: another Cloudflare account proxies the address. Fix: set its record to DNS only.
certificate_timed_out: validation timed out; check the records are still in place.
certificate_blocked and records_write_failed: next_action is contact_support.

When the domain connects, the merchant also gets a notification.

4. Assign it to a storefront#

A connected, unassigned domain has next_action.key assign_storefront. Call list_storefronts, let the merchant choose, then call assign_storefront_domain with domain_id and storefront_id. To make it the storefront's primary address, call set_primary_domain with confirmed: false, show the returned warnings, and after approval repeat with confirmed: true, the confirmation_token and a verification code (step 7). set_country_domain serves a country from the domain; list_country_urls shows the resulting addresses.

5. Keep it healthy#

Connected domains are re-checked every 6 hours; setup.last_checked and setup.next_check show when. If the domain stops pointing to Tringify, issue.key is dns_warning: its message says what public DNS shows instead, fix what to change, and deadline when the domain stops opening the store (72 hours after the first failed check). After the merchant fixes it, verify_domain re-checks at once and the warning clears. Past the deadline the issue is disconnected; the domain reconnects by itself once its DNS is right.

json

{
  "badge": {
    "label": "Needs attention",
    "tone": "warning"
  },
  "issue": {
    "key": "dns_warning",
    "title": "shop.example.com can't be reached through its DNS",
    "message": "Public DNS shows old-host.example.net for shop.example.com instead of custom.mytringify.com.",
    "fix": "At your DNS host, point shop.example.com to custom.mytringify.com with a CNAME record again. Tringify checks again automatically; you can also check now.",
    "since": "2026-10-27T06:00:00-04:00",
    "deadline": "If it isn't fixed by Oct 30, 2026, 6:00 AM, shop.example.com stops opening your store. It reconnects by itself once its DNS is right."
  },
  "next_action": {
    "key": "fix_dns",
    "label": "Point shop.example.com back to Tringify",
    "tool": "verify_domain",
    "arguments": {
      "domain_id": "3f0d9a8e-6a7b-4c2d-9e1f-5a4b3c2d1e0f"
    }
  }
}

If a primary domain is disconnected, another address becomes primary and issue.key is primary_fallback, naming the address that took over. Once the domain is connected again, next_action.key is set_primary_again with set_primary_domain; Tringify doesn't switch back by itself.

6. Hosted DNS#

A root domain on the nameservers path has a DNS zone Tringify hosts (dns_zone_id, actions includes manage_dns). get_dns_zone returns its records and a view with state_label, tone, working (read again after poll_after_ms) and operation, the one change to show (status queued, applied, failed or cancelled with label and message). Record changes answer HTTP 202: follow the returned operation_id with get_dns_operation. Imports and exports run as jobs (list_dns_jobs, list_dns_job_errors, get_dns_export_download). Records Tringify writes for the storefront and email are not editable.

7. Verification codes#

Removing a domain, setting up hosted DNS, changing DNS records, unassigning a domain and setting or clearing the primary domain need the same verification code Store Admin asks for. Never guess one. When a tool refuses a missing or wrong code, the error's details.next_action is the exact request_verification_code call:

json

{
  "success": false,
  "error": {
    "code": "DOMAIN_REMOVAL_OTP_REQUIRED",
    "message": "Verification code is required.",
    "details": {
      "verification": {
        "action": "remove_domain",
        "target_type": "domain",
        "target_id": "3f0d9a8e-6a7b-4c2d-9e1f-5a4b3c2d1e0f"
      },
      "next_action": {
        "key": "request_code",
        "label": "Confirm with a verification code",
        "message": "This change needs a verification code. Tringify emails it to you; enter it to confirm.",
        "tool": "request_verification_code",
        "arguments": {
          "action": "remove_domain",
          "target_type": "domain",
          "target_id": "3f0d9a8e-6a7b-4c2d-9e1f-5a4b3c2d1e0f"
        }
      }
    }
  }
}

Get the merchant's approval for the change.
Call request_verification_code with those arguments. Tell the merchant the code went to sent_to.
Ask the merchant for the code and call the tool again with otp_code before expires_at. Don't request another before resend_available_at.

8. Remove the domain#

Call check_domain_removal and show its confirm sentence and every impacts[].message: the hosted DNS and its record count, sending domains and sender addresses removed with it, the address store emails come from instead, and that the domain is free for any store afterwards. After the merchant approves, call its next_action (request_verification_code), ask for the code and call delete_domain with domain_id and otp_code.

A domain that can't be removed yet is refused with a message and details.next_action:

DOMAIN_ASSIGNED_TO_STOREFRONT names the storefront. Unassign with assign_storefront_domain and an empty storefront_id (it needs its own unassign_domain code); if it was the primary address another address becomes primary.
DOMAIN_DNS_NAMESERVERS_IN_USE lists the Tringify nameservers the domain still uses. The merchant copies the records they need, sets the registrar's nameservers back to their DNS host's, and once public DNS shows the change you call check_domain_removal again. The domain keeps working meanwhile.
DOMAIN_DNS_NAMESERVER_CHECK_FAILED: the nameservers couldn't be looked up; try again.

See the Domains reference for every field and the OAuth and MCP reference for the tool list.