MCP tool reference

Server endpoint: https://domainfind.ai/api/mcp (streamable HTTP). Setup instructions live in the developer quickstart. All tools return a single JSON text block designed for direct agent consumption.

`check_domain`

Verify one domain's availability at the registry.

Parameters

{ "domain": "examplebrand.ai" }

Example response

{
  "query_status": "SUCCESS",
  "domain": "examplebrand.ai",
  "tld": "ai",
  "status": "available",          // available | registered | unknown | invalid
  "method": "rdap",               // rdap | dns | none
  "confidence": 0.97,
  "minYears": 2,
  "registrars": [
    {
      "registrar": "Spaceship",
      "firstYearUsd": 68.98,
      "renewalUsd": 68.98,
      "buyUrl": "https://www.spaceship.com/domain-search/?query=examplebrand.ai"
    }
  ]
}

`check_domains`

Bulk-check a shortlist of full domains (up to 50) in one call.

Parameters

{ "domains": ["polynesianvoices.com", "pacificvoice.ai", "islandvoices.com"] }
// or a raw pasted string — bullets, commas, and newlines are parsed:
{ "domains": "* polynesianvoices.com\n* pacificvoice.ai" }

Example response

{
  "query_status": "SUCCESS",
  "summary": { "checked": 3, "available": 2, "registered": 1, "unknown": 0 },
  "results": [ { "domain": "pacificvoice.ai", "status": "available", ... } ],
  "skipped": []                   // tokens that were not valid domains
}

`search_domains`

Sweep one keyword across multiple TLDs in a single call.

Parameters

{ "keyword": "examplebrand", "tlds": ["com", "ai", "io"] }

Example response

{
  "query_status": "SUCCESS",
  "keyword": "examplebrand",
  "available": [ { "domain": "examplebrand.ai", "confidence": 0.97, "registrars": [...] } ],
  "registered": [ { "domain": "examplebrand.com", "registrar": "GoDaddy Inc." } ],
  "unknown": []
}

`suggest_domains`

Generate brandable candidates from a business description (8 naming styles), each verified for availability.

Parameters

{
  "description": "AI voice agents for dental offices",
  "tlds": ["com", "ai"],
  "max_candidates": 8
}

Example response

{
  "query_status": "SUCCESS",
  "suggestions": [
    {
      "domain": "voicedental.ai",
      "status": "available",
      "style": "compound",
      "rationale": "Joins \"voice\" + \"dental\" into one brandable compound.",
      "confidence": 0.97,
      "registrars": [...]
    }
  ],
  "note": "Filter on status === 'available'."
}

`get_tld_pricing`

Registrar price matrix + registry rules for one TLD.

Parameters

{ "tld": "ai" }

Example response

{
  "query_status": "SUCCESS",
  "tld": "ai",
  "category": "ccTLD (treated as generic)",
  "minYears": 2,
  "registrars": [
    { "registrar": "Spaceship", "firstYearUsd": 68.98, "renewalUsd": 68.98, "note": "Lowest baseline .ai cost" },
    { "registrar": "GoDaddy", "firstYearUsd": 49.99, "renewalUsd": 159.99, "note": "Intro price requires 2-yr commitment" }
  ]
}

Semantics agents should rely on

status is the decision field; confidence is how much to trust it. RDAP-verified answers score ≥ 0.97; DNS-inferred answers ~0.75.
registrars is populated (sorted by first-year price ascending, each with a direct buyUrl) only when status === "available" AND the TLD is priced. It is an empty array [] for registered, reserved, or unsupported-TLD results.
status can also be reserved (RFC 2606/6761 names like example.com — never registrable) or invalid (malformed input). When an available name carries unsupportedTld: true, it looks unregistered but has no buy path yet — don't present it as purchasable.
pricesVerifiedAt stamps the maintained price matrix. Pricing is a reference table of standard registration costs, not a live per-name quote, and does not reflect registry premium tiers — an agent should treat it as guidance and let the human confirm at checkout.
minYears flags registry minimum terms (e.g. .ai requires 2 years) — multiply accordingly when reporting cost to a human.
Internationalized domains are accepted and punycode-encoded automatically (e.g. münchen.ai → xn--mnchen-3ya.ai).
Tools are idempotent and side-effect-free: DomainFind.ai never registers, reserves, or front-runs a queried name. See domain front-running.

Rate limits & authentication

MCP tool calls draw from the same daily quota as the REST API, counted per API key (or per client IP when anonymous):

Tier	Requests / day	How
Anonymous	50 / IP	No key — works out of the box
Free	500	POST your email to `/api/keys`
Pro	10,000	See pricing
Scale	100,000	See pricing

To raise your limit, attach your key as a header in the MCP server config. Any MCP client that supports custom headers works:

{
  "mcpServers": {
    "domainfind": {
      "url": "https://domainfind.ai/api/mcp",
      "headers": { "x-api-key": "df_live_..." }
    }
  }
}

When the daily quota is exhausted, tool calls return an error result explaining the limit and pointing to upgrade options — the server stays responsive; only the quota is enforced.