CustomDomain™

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

Website · Docs · Console · Product page · MCP docs · Tool reference · Provider coverage · Pricing

CustomDomain™ MCP is a hosted Model Context Protocol 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.

flowchart LR
  A["AgentClaude · Cursor · ChatGPT"] -->|"JSON-RPC over HTTPS"| M["mcp.customdomain.ai12 tools"]
  M -->|"Bearer forwarded"| C["Control planeapi.customdomain.ai"]
  C --> R["Registrarssearch · buy"]
  C --> D["DNS providers63 catalogued · 25 automatic"]
  C --> E["EdgeTLS 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™ 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.

The receipts, all verifiable from outside: the server is published in the official MCP registry as ai.customdomain/mcp at 0.4.0, speaks protocol revision 2025-06-18, and answers an unauthenticated call with a RFC 9728 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. 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:

claude mcp add --transport http customdomain https://mcp.customdomain.ai/mcp \
  --header "Authorization: Bearer sk_live_YOUR_KEY"

Cursor: add to .cursor/mcp.json:

{
  "mcpServers": {
    "customdomain": {
      "url": "https://mcp.customdomain.ai/mcp",
      "headers": { "Authorization": "Bearer sk_live_YOUR_KEY" }
    }
  }
}

Any HTTP client: the endpoint is plain JSON-RPC 2.0, so you can call a tool with curl:

curl -X POST https://mcp.customdomain.ai/mcp \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"discover-provider","arguments":{"domain":"example.com"}}}'

Claude Desktop reaches HTTP servers through mcp-remote; ChatGPT reaches them as a developer-mode connector. Both configs are on the product page.

Client support

Tools and the two conventions

Two rules run through every tool, and they are the two things integrators get wrong.

No tool accepts a DNS record. add-email takes mail settings (an MX host, a DKIM selector) and the template turns those into records. forward-domain takes a redirect target. Neither takes a record.

connected: true is the completion signal. Status strings are informative; the boolean is what you branch on, and it stays stable if the status enum ever grows.

There is also no ownership-challenge step: no tool asks for or checks a TXT verification record. Control of the domain is proven by the rail that writes the records (an OAuth authorization at the provider, a one-click apply, or a scoped API token), and on the manual path the control plane simply waits for the records to appear in public DNS.

Authentication

POST /mcp accepts three bearer credentials.

curl -X POST https://mcp.customdomain.ai/token \
  -u "<APPLICATION_ID>:<CLIENT_SECRET>" \
  -d "grant_type=client_credentials"
# -> { "access_token": "eyJ...", "token_type": "Bearer", "expires_in": 900 }

APPLICATION_ID and CLIENT_ID are the same value under two names. Prefer the JWT when an agent only needs one application: a leaked sk_live_ key carries the whole tenant. The server does not validate credentials itself; it forwards the bearer to the control plane, which enforces the same application-scoped permissions as the REST API, so revoking a key in the console cuts the agent off on its next call. See Authentication.

Lifecycle, polling and errors

Connections move pending → propagating → live. failed is a diagnosis, not a tombstone.

The background poller re-checks about once a minute, so polling faster than every 30 to 60 seconds gains nothing. failed is recoverable and is not a reason to tell a user to start over. The full lifecycle is at Connections.

Errors come in two shapes. A malformed call fails at the JSON-RPC layer: -32602 for invalid parameters, -32601 for an unknown tool, -32700 for unparseable JSON. Those are caller bugs. A call the control plane refused comes back as a normal tool result:

{ "success": false, "error": "connect_failed", "message": "Domain already connected to another application" }

Branch on error; show message.

How it works

This repository is the public face of a hosted service: the registry manifest that lists the server, the tool contract, and this page. The server itself is a small Go process. It terminates JSON-RPC, checks nothing it does not have to, and forwards each tool call to the CustomDomain™ control plane, which owns provider detection, the record templates, the registrar rails, the propagation poller and certificate issuance. That split is why the tool surface can stay this narrow: all the state and all the judgment live one hop away.

Repository layout

.
├── README.md      # this file: what the server is, how to point a client at it, how it is built
├── TOOLS.md       # the tool contract: every argument, every response field, every status value
├── CHANGELOG.md   # one entry per server version, matching the tags and GitHub releases
├── server.json    # MCP registry manifest: name ai.customdomain/mcp, version 0.4.0, remote endpoint
├── glama.json     # Glama directory ownership claim
└── LICENSE        # MIT

Service modules

The server source lives in the private CustomDomain™ monorepo under services/mcp, alongside the control plane it calls. Named here so the boundaries are legible, not linked, because the repository is closed.

Entry point: services/mcp/cmd/mcp/main.go.

The flow that matters

Connecting a domain someone already owns is the flow everything else is shaped around.

sequenceDiagram
  participant A as Agent
  participant M as mcp.customdomain.ai
  participant C as Control plane
  participant D as Customer's DNS
  participant E as Edge
  A->>M: tools/call connect-domain {domain}
  M->>C: POST /v1/connections (bearer forwarded)
  C->>C: detect provider, choose rail, compute records
  C-->>M: jobId, records[], link, managed
  M-->>A: same payload as structuredContent
  Note over A,D: automatic rail: user authorizes oncemanual rail: user adds the returned records
  C->>D: poll public DNS by value (~60s)
  C->>E: request certificate once records resolve
  A->>M: tools/call check-connection-status {jobId}
  M-->>A: status live, connected true

Invariants

• No tool accepts a DNS record as input. Record values are computed server-side from vetted templates. This is the security model, not a gap.
• The server has no database. Its go.mod pulls Sentry and OpenTelemetry and nothing else; every fact a tool returns was fetched from the control plane during that request.
• There is no ownership-challenge step. No tool asks for or checks a TXT verification record.
• Nothing in this repository is deployed. No build, no CI, no server source: the files here are read by the MCP registry and by people, and the endpoint ships from elsewhere.
• POST /v1/connections is idempotent per application and domain, so a repeated connect-domain resumes the existing connection and returns already_connected: true rather than creating a second one.

Configuration

What you set, as a client. There are no environment variables to set in this repository.

Keep the key out of the config file where your client supports it. If it lives in a secrets manager, inject it at launch; never paste a literal key into a repository, a .cursor/mcp.json you commit, or an