customdomain-mcp

# CustomDomain™ MCP

The MCP server for custom domains: let Claude and other AI agents search, buy, connect and verify domains.

**Status:** Production · server 0.4.0 · release [v0.4.0](https://github.com/CUSTOM-DOMAIN-APP/customdomain-mcp/releases/tag/v0.4.0)

[![live](https://img.shields.io/badge/live-mcp.customdomain.ai-1c1917?style=flat)](https://customdomain.ai/mcp-server)
[![MCP registry](https://img.shields.io/badge/MCP%20registry-ai.customdomain%2Fmcp-1c1917?style=flat)](https://registry.modelcontextprotocol.io/v0/servers?search=ai.customdomain%2Fmcp)
[![protocol](https://img.shields.io/badge/protocol-2025--06--18-1c1917?style=flat)](https://docs.customdomain.ai/docs/mcp/overview)
[![docs](https://img.shields.io/badge/docs-docs.customdomain.ai-1c1917?style=flat)](https://docs.customdomain.ai/docs/mcp/overview)
[![license](https://img.shields.io/badge/license-MIT-1c1917?style=flat)](./LICENSE)

[Website](https://customdomain.ai) · [Docs](https://docs.customdomain.ai/docs) · [Console](https://app.customdomain.ai) · [Product page](https://customdomain.ai/mcp-server) · [MCP docs](https://docs.customdomain.ai/docs/mcp/overview) · [Tool reference](./TOOLS.md) · [Provider coverage](https://docs.customdomain.ai/docs/providers) · [Pricing](https://customdomain.ai/pricing)

|  |  |
|---|---|
| **What it is** | A hosted MCP server that gives an AI agent twelve domain tools |
| **Who it's for** | Agent builders, SaaS platforms and coding-agent users who need a customer on their own domain |
| **Live at** | [customdomain.ai/mcp-server](https://customdomain.ai/mcp-server) · endpoint `https://mcp.customdomain.ai/mcp` |
| **Stack** | Go 1.25 · JSON-RPC 2.0 over streamable HTTP · hosted, no datastore in the server |
| **Status** | Production · 0.4.0 in the official MCP registry · 12 tools · 63 DNS providers catalogued, 25 automatic |

CustomDomain™ MCP is a hosted [Model Context Protocol](https://modelcontextprotocol.io) server that lets an
AI agent put a person on their own domain: find one, buy it, connect one they already own, set up its email
records, and watch it go live with HTTPS. It replaces the part of that job a human normally does by hand in a
DNS control panel. There is nothing to install and nothing to keep running: point your MCP client at the
endpoint above.

```mermaid
flowchart LR
  A["Agent<br/>Claude · Cursor · ChatGPT"] -->|"JSON-RPC over HTTPS"| M["mcp.customdomain.ai<br/>12 tools"]
  M -->|"Bearer forwarded"| C["Control plane<br/>api.customdomain.ai"]
  C --> R["Registrars<br/>search · buy"]
  C --> D["DNS providers<br/>63 catalogued · 25 automatic"]
  C --> E["Edge<br/>TLS issued"]
```

---

## The problem

Every SaaS product eventually needs a customer on their own domain: a white-label app host, a vanity link, a
sending domain for email. The work is small and it is always the same: figure out who runs the customer's DNS,
write the right records in the right shapes, wait for them to propagate, then get a certificate. Done by hand
it is a support ticket. Done in code it is a DNS provider integration you did not want to own, times sixty.

Agents make this worse before they make it better. The obvious way to let an agent do the job is to give it
DNS credentials and a way to write records, which means one confused turn or one poisoned web page can now
edit a customer's zone. Nobody wants to hand a language model a `SetRecords` call on a production domain, and
the alternative (an agent that reads instructions aloud and asks the user to go type them somewhere) is the
support ticket again, with extra steps. That is not a permissions problem you can prompt your way out of; it
is an argument-list problem, and it gets solved by changing what the agent is able to say.

## Who it's for

- **Teams building agents that ship things.** A coding agent, a site builder, a deploy bot: anything whose
  output is a running app that needs an address a person will actually type. The agent does the whole job in
  four tool calls instead of stopping at the last mile with a paragraph of DNS instructions.
- **SaaS platforms with tenant domains.** If your customers connect their own domain to your product, this is
  the same engine the [CustomDomain™](https://customdomain.ai) widget and REST API run on, reached through the
  protocol your agents already speak.
- **Email and messaging platforms.** Getting a sending domain authenticated (MX, SPF, DKIM, DMARC, in the
  right shapes, at the customer's provider) is one call here instead of a documentation page and a support
  queue.
- **Anyone with a domain portfolio to keep alive.** Connections drift, certificates need records that still
  resolve, and an agent that can list, diagnose and re-apply is cheaper than a person doing it quarterly.

## What it does

Twelve tools, one credential, no DNS records in any argument. Each of these is a tool call, not a workflow you
have to assemble:

- **Check whether a domain can be registered**, with live purchase and renewal pricing: `search-domain-availability`
- **Suggest names that are actually free**, deterministically, from a set of keywords: `generate-domain-suggestions`
- **Register a domain** through the resolved registrar, behind a fail-closed authorization gate: `create-domain-order`
- **Connect a domain the customer already owns** and get back the exact records that must exist: `connect-domain`
- **Detect the DNS provider before you ask anyone for anything**, with conflict and CAA pre-flight: `discover-provider`
- **Poll a connection to completion**, from records written to certificate issued: `check-connection-status`
- **Poll a registration order** across two different ledgers without guessing which one applies: `check-order-status`
- **Set up email in one call** (MX, SPF, DKIM and DMARC from a server-side template): `add-email`
- **Point a domain somewhere permanently** with a 301: `forward-domain`
- **Repair a domain that drifted** out of `live`, using a stored grant: `reapply-connection`
- **Take a domain down cleanly**, reverting its DNS first: `disconnect-domain`
- **Inventory the whole account** so an agent can reconcile a portfolio, not just the job it started: `list-connections`

Full arguments and response shapes: **[TOOLS.md](./TOOLS.md)**.

The receipts, all verifiable from outside: the server is published in the official MCP registry as
[`ai.customdomain/mcp`](https://registry.modelcontextprotocol.io/v0/servers?search=ai.customdomain%2Fmcp) at
0.4.0, speaks protocol revision `2025-06-18`, and answers an unauthenticated call with a
[RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) challenge that names its own metadata document
rather than a bare 401. Automatic setup covers **25 of the 63 DNS providers catalogued** (17 by scoped API
token, 6 by provider OAuth, 2 by provider-hosted one-click), and the other 38 still work, returning records
and a link for a human to apply.

Every one of those tools was built against the same lesson: an agent that returns a console link and stops has
not done the job. The tools return the authoritative record set itself, so the agent can tell a person exactly
what to add, and the completion signal is a boolean rather than a status string an integration can misread.

## Use cases

- **A coding agent shipping a side project.** "Find me a domain under $20, buy it, and point it at this app."
  Search, order, connect, poll: four calls, no console visit.
- **A SaaS onboarding an enterprise customer.** The agent calls `discover-provider` first, sees the customer
  runs a provider that cannot hold a root-domain alias, and warns before anyone authorizes anything.
- **An email platform.** `add-email` writes MX, SPF, DKIM and DMARC from a template; the agent supplies the
  per-domain DKIM selector and nothing else.
- **A platform with a thousand tenant domains.** `list-connections` with `status=failed`, keep the rows with
  `managed: true`, `reapply-connection` on those, escalate the rest to a human. That is a reconciliation loop
  an agent can run on a schedule, and it is the reason the inventory tool exists at all.
- **A support agent answering "why is my domain not working yet".** `check-connection-status` returns the
  status, the records, and an error code that distinguishes "the records were never added" from "they were
  added and have not propagated". Those are two different replies to the customer.

## Why an MCP server and not a REST API

There is a REST API, and it is the thing this server calls. The difference is what an agent is allowed to say.
The REST API accepts DNS records; the MCP tools do not. Every record value is computed by the control plane
from a vetted template, so the worst thing a prompt-injected agent can do here is connect the wrong domain,
not write an arbitrary `MX` record into a customer's zone. The security model is the argument list. Paid
registration is gated separately: `create-domain-order` places an order only after the integrator's
purchase-authorization callback approves it, and an unconfigured callback denies every purchase.

The second reason is discovery. An agent that has never heard of this product can find it: the server is in
the official MCP registry, it publishes an agent manifest and an OAuth protected-resource document at
well-known paths, and an unauthenticated call answers with a challenge naming its protected-resource document
rather than a bare 401. A REST API cannot introduce itself that way. The manifest carries the intent keywords
a person would actually use (connect a domain, bring your own domain, white-label domain, set up email for a
domain), so the match happens before anyone writes an integration.

---

## Quickstart

Get an API key from the console at [app.customdomain.ai/signup](https://app.customdomain.ai/signup). Keys look
like `sk_live_...` and are shown once, at creation. The Free plan covers every tool here except
`create-domain-order`, which places a real paid registration.

**Claude Code**, one command:

```bash
cla