MCP server

Customdomain ships a Model Context Protocol (MCP) server so an AI agent can search for, register, and connect domains through the same control-plane /v1 API — without ever handling DNS records itself. It runs as a separate process (services/mcp) and wraps the control-plane; it adds no business logic of its own.

The hosted endpoint is live at https://mcp.customdomain.ai/mcp (Streamable HTTP). The console's MCP server page (under Integrate, at /app/mcp) has the endpoint, the token URL, and copy-paste client configs for HTTP-native hosts and the mcp-remote stdio bridge.

The server reports itself as customdomain-mcp (protocol revision 2025-06-18) and advertises only the tools capability.

Tools

The server registers twelve tools, in a fixed order. None of them takes DNS records as input — records always come from the control-plane server-side, so an agent can never inject them.

generate-domain-suggestions is deterministic, not AI. Candidates are keyword joins plus a few common affixes (get, try, use, my, …app, …hq), expanded across TLDs by the registrar search and filtered to what's actually available. No LLM is involved — the same keywords always produce the same candidates, which keeps the tool predictable and testable.

create-domain-order is fail-closed. The server places a paid order only after a successful call to the integrator's purchase-authorization callback (MCP_PURCHASE_AUTHZ_URL, HTTP Basic). If that callback is unset, every purchase is denied — the safe default. Registrar purchasing is also gated on the control-plane by SELL_PURCHASE_ENABLED (fail-closed unless it's set). On the hosted service, purchasing is live through the money-safe checkout — see Buying a domain.

Transports

The server binary (cmd/mcp) speaks two transports, selected with -transport:

• stdio (default) — line-delimited JSON-RPC on stdin/stdout, one message per line. This is what a locally-launched host (or mcp-remote) uses when it runs the server as a subprocess. It authenticates with a single static control-plane credential (-bearer, or CUSTOMDOMAIN_API_TOKEN — the legacy JUSTEASY_API_TOKEN is still read as a fallback).

• http — a Streamable-HTTP style endpoint. Three routes:

  Route	Purpose
  POST /mcp	The MCP JSON-RPC endpoint. Requires Authorization: Bearer (unless started with -insecure for local dev).
  POST /token	OAuth 2.0 client-credentials grant — exchange client_id + client_secret for a short-lived Bearer.
  GET /healthz	Liveness.

The hosted server is at https://mcp.customdomain.ai (the MCP endpoint is POST https://mcp.customdomain.ai/mcp).

Authentication

POST /token proxies the control-plane's POST /v1/tokens: it exchanges an application's client_id + client_secret (also accepted as application_id) for a widget JWT. Credentials may be sent as HTTP Basic auth, form fields, or a JSON body; the only supported grant_type is client_credentials.

# Mint a short-lived Bearer
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": 3600 }

POST /mcp accepts three Bearer forms, so hosts that can't run the token dance still authenticate:

1. a JWT minted by /token,
2. a console API key (sk_live_… / sk_test_…),
3. the mcp-remote shortcut CLIENT_ID:CLIENT_SECRET, which the server exchanges for a JWT on the fly.

The MCP server never validates tokens cryptographically itself — it forwards the caller's credential to the control-plane, which is the authority and rejects bad credentials on every wrapped call.

Coming later: delegated agent tokens. The MCP also contains a resource-server path that verifies short-lived ES256 tokens locally against the control-plane's JWKS (no per-request callback) and scope-enforces them per tool, for a human owner delegating access to an AI agent. It is built and tested but not yet enabled on the hosted service. See Agent access for the human-first consent flow this will support once activated.

# Call a tool
curl -X POST https://mcp.customdomain.ai/mcp \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"search-domain-availability","arguments":{"domain":"example.com"}}}'

Configuration

The http transport reads these (flags shown; each has an env alias):