Custom Domain API MCP server

Custom Domain

Custom domains for multi-tenant SaaS products. Applications register their customers' hostnames through an API, hand back exact DNS instructions, and are told when each hostname is verified, certified and serving. The edge (Caddy) obtains certificates on demand and forwards every request to the application's origin with a signed assertion that names the workspace the hostname belongs to, so the application never selects a tenant from the Host header.

Several applications share one deployment. Each has its own credentials, its own verified origin and its own hostnames; nothing an application does can affect another's.

Integration guides (quickstart, API, verifying requests, webhooks, and a brief for AI coding agents) are at customdomainapi.com/docs, also as Markdown for agents (llms.txt). The same service is run as a hosted option at customdomainapi.com.

How it works

control of it (the origin serves a token at /.well-known/custom-domain-origin-verification), then issues an API credential.

1. The operator creates an application, registers its origin and proves

opaque workspace reference. The answer carries the two records the customer must publish: a TXT record proving ownership and a CNAME to the edge.

1. The application calls POST /v1/domains with a customer hostname and an

and asks the origin, through the edge, which workspace it serves for the hostname. The domain becomes ready only when ownership, routing, certificate and origin checks all pass. Drift later moves it to attention_required; a lost TXT record suspends it after 24 hours.

1. The lifecycle worker checks DNS, obtains the certificate through the edge

HMAC-signed token binding the request to the application, domain, workspace reference and hostname. The SDK middleware verifies it and exposes the workspace to the application.

1. Every request the edge proxies carries X-Custom-Domain-Assertion, an

domain.attention_required, domain.recovered, domain.deleted), with history and replay. Deleting a domain stops service on the next request.

1. Status changes are delivered as signed webhooks (domain.ready,

Only exact customer subdomains are supported (no apex or wildcard names).

Quick start (single container)

Create a .env file:

DATABASE_URL=sqlite:///data/custom_domain.db
ENABLE_LEGACY_API=false
EDGE_ASSERTION_KEYS=1:<at least 32 random characters>
ACME_EMAIL=ops@example.com
CADDY_STORAGE=file

EDGEASSERTIONKEYS signs the assertions the edge attaches to proxied requests; generate the secret with python -c "import secrets; print(secrets.tokenurlsafe(48))". Use a PostgreSQL URL such as postgresql+psycopg://user:password@db:5432/customdomain for anything beyond a trial. All settings are listed in .env_example.

Run the image:

docker volume create https_data && docker volume create https_db && docker volume create https_domains
docker compose up -d

The bundled docker-compose.yml publishes ports 80 and 443 and binds the management API to 127.0.0.1:9000. With PUBLICAPI=true and EDGEHOSTNAME set, the edge also serves the v1 API at https:///v1 for applications (nothing else of the API is routed); the production installer turns this on. Swagger UI is at http://localhost:9000/v1/docs; the OpenAPI document is served at /v1/openapi.json and committed as docs/openapi.json.

For production, use deploy/compose.production.yml: PostgreSQL, Redis-backed certificate storage, and separate API, worker and edge containers with the edge's admin API behind a validating gateway. The walkthrough, backups, monitoring and rollback are in docs/deployment.md.

Try it locally

Shortened. The full README is on GitHub.