← DNS Lookup

Learn More

This document outlines the architecture and capabilities of the DNS Lookup service, a fully serverless platform on Cloudflare's edge that provides raw DNS-over-HTTPS, structured JSON APIs, and AI-agent interfaces.

Three ways to use it

All three are free, need no account or API key, and allow requests from any website (CORS).

1. DoH DNS over HTTPS, RFC 8484

For browsers, operating systems and any app that accepts a custom DoH server. Enter this as the server address:

https://domainnamesystem.pages.dev/

It accepts GET /?dns=<base64url> and POST with Content-Type: application/dns-message. To try it, let curl do the DNS work, or fetch a raw answer:

curl --doh-url https://domainnamesystem.pages.dev/ https://example.com

curl -s -H 'accept: application/dns-message' \
  'https://domainnamesystem.pages.dev/?dns=AAABAAABAAAAAAAAA3d3dwdleGFtcGxlA2NvbQAAAQAB' | xxd

2. JSON API for scripts, apps and anything that prefers JSON

One GET request returns decoded records. type is optional and comma-separated; leave it out for A, AAAA, CNAME, MX, TXT and NS, or use ALL for every supported type.

curl 'https://domainnamesystem.pages.dev/resolve?name=gmail.com&type=MX'

Example response (values vary):

{
  "name": "gmail.com",
  "status": "NOERROR",
  "queried": ["MX"],
  "answers": [
    { "name": "gmail.com", "type": "MX", "ttl": 3600,
      "data": "5 gmail-smtp-in.l.google.com" }
  ]
}

Read status and hint: NXDOMAIN means the domain does not exist, and NOERROR with empty answers means it exists but has no such records. The full schema is in openapi.json.

3. MCP for AI assistants and agents

A Model Context Protocol server over Streamable HTTP, no authentication. It exposes one tool, dns_lookup, with the arguments name and optional type. In Claude Code:

claude mcp add --transport http dns-lookup https://domainnamesystem.pages.dev/mcp

Other MCP clients: add a remote (HTTP) server with the same URL. To call the tool by hand:

curl -s https://domainnamesystem.pages.dev/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"dns_lookup","arguments":{"name":"gmail.com","type":"MX"}}}'

There is also an A2A agent at /a2a, and a short guide for agents in llms.txt.

How it works

1. The big picture

Cloudflare Pages serves the static page and runs _worker.js in front of it. The Worker accepts standard DoH requests (RFC 8484), answers from cache when it can, and otherwise asks Google Public DNS (dns.google/dns-query). On the way it adds client-subnet hints, caching, CNAME flattening and special handling for HTTPS records.

Client browsers · agents Worker parse · route · cache at the Cloudflare edge dns.google DoH upstream DoH / JSON + ECS L1 memory L2 Cache API Workers KV

2. Life of a request

  1. Receive. The query arrives as GET /?dns=<base64url> or as a POST with Content-Type: application/dns-message. Anything over 4096 bytes is rejected (413) and malformed input gets 400. The Worker reads the question: the name (lower-cased) and the record type.
  2. Add the client subnet. Your address (CF-Connecting-IP) is truncated and attached as an ECS option (section 4).
  3. Route. Most queries go straight to the cache and upstream path. HTTPS-type queries may take the special path in section 7.
  4. Cache, then upstream. A hit is served immediately. A miss goes to Google Public DNS with a 1.5 s timeout. If upstream fails, the client gets a proper DNS SERVFAIL rather than a hang.
  5. Clean up. CNAME chains are flattened for A, AAAA and HTTPS answers, the ECS option is stripped from the cached copy, and the message ID and question are rewritten to match your query, with TTLs reduced by the entry's age.
  6. Reply with application/dns-message, Cache-Control: max-age=<remaining TTL> and Access-Control-Allow-Origin: *.

3. Working with raw DNS messages

A DoH body is an ordinary DNS message (RFC 1035) in binary wire format. The Worker reads and edits those bytes directly with typed arrays and DataView, with no DNS library, which keeps it small and fast. The pieces that matter:

  1. Layout. A 12-byte header (ID, flags and four record counts), then the question, then the answer, authority and additional sections.
  2. Names. A name is a series of length-prefixed labels ending in a zero byte. A two-byte compression pointer (top two bits set; 0xC00C means "the name at offset 12", the question) can stand in for a name that already appeared. The parser follows pointers, and the Worker lower-cases the name before using it for routing and cache keys.
  3. The OPT record. EDNS(0) (RFC 6891) lives in the additional section as a pseudo-record that carries flags such as DNSSEC-OK and options such as ECS. To add a client subnet the Worker either appends an option to the existing OPT record and fixes its length, or appends a new OPT record and bumps the additional-record count.
  4. In-place edits. To serve a cached answer it copies the stored bytes, overwrites the ID and question with the caller's, and subtracts the entry's age from each TTL, at offsets recorded when the entry was stored.
  5. Synthesized answers. The HTTPS answers in section 7 are assembled byte by byte in a reusable scratch buffer: header, echoed question, then a record whose name is a pointer back to the question.
  6. Address matching. IPv4 addresses are compared as 32-bit integers and IPv6 addresses by their leading 64 bits, against sorted start and end arrays.

4. Client subnet (ECS)

Many CDNs pick a server based on where the resolver is. Google Public DNS only sees Cloudflare's address, not yours, so left alone it would steer you by the wrong location. The Worker therefore forwards a truncated copy of your address (a /24 for IPv4, a /32 for IPv6) in the EDNS Client Subnet option (RFC 7871), so answers are tuned to your network.

The trade-off is privacy: that prefix is shared with the upstream resolver. If your query already carries its own ECS option, the Worker leaves it untouched and does not cache that query.

5. Caching

  1. Key. Record type, class, name, the DNSSEC-OK and Checking-Disabled flags, and the client-subnet bucket. Answers the upstream marks as location-independent (ECS scope 0) are stored once in a shared entry; the rest are cached per subnet.
  2. Two layers. L1 is an in-memory LRU inside the Worker (up to 10,000 entries). L2 is Cloudflare's Cache API in the local data center.
  3. TTL. The smallest TTL among the answer and authority records, capped at 300 s. Truncated responses and failures (anything except NOERROR and NXDOMAIN) are not cached.
  4. Stale-while-revalidate. For up to 60 s after expiry an entry may still be served while a background request refreshes it.
  5. Request coalescing. Simultaneous identical lookups share a single upstream request.
  6. Honest TTLs. TTLs in the reply count down with the entry's age, so downstream caches never hold a record longer than intended.

6. CNAME flattening

For A, AAAA and HTTPS queries, if the upstream answer contains a CNAME chain (www.example.com → cdn.example.net → an address), the Worker drops the CNAME records and rewrites the remaining records so they belong to the name you asked for. The client gets the final addresses in one hop and a smaller packet. One consequence: a plain A lookup of an aliased name does not show the chain; query CNAME explicitly to see it.

7. HTTPS records and ECH

HTTPS records (type 65, RFC 9460) tell a browser how to connect before it connects: which protocols the server speaks (h2, h3), IP hints, and, for Encrypted Client Hello (ECH), the public configuration needed to hide the server name (SNI) in the TLS handshake. For this record type the Worker first works out who hosts the domain:

  1. Known domains. A built-in list of domains the Worker assumes are served by Cloudflare (for example x.com, discord.com) or by Meta (for example facebook.com, instagram.com), matched on the domain and its subdomains.
  2. IP hints. Otherwise it reads ipv4hint / ipv6hint from the upstream answer and checks them against Cloudflare and Meta address ranges.
  3. Probe. With no hints, it resolves the A record and checks those addresses instead.

The address ranges live in Workers KV as compiled, sorted arrays and are checked by binary search, so a check costs only a few comparisons. The verdict is remembered for an hour (one minute if the ranges could not be loaded), in memory and in the Cache API.

For Cloudflare-hosted names the Worker replaces the answer with a synthesized one built from the ALPN and ECH parameters of the HTTPS record of cloudflare-ech.com (fetched upstream and refreshed every 15 minutes) and served with a 300 s TTL. If that configuration cannot be fetched, the client gets an empty answer with a 60 s TTL, so the browser simply connects without ECH. For Meta-hosted names the same kind of record is built with priority 1, ALPN h2 and h3, and an ECH configuration stored in KV; if none is available the upstream answer is returned. Everything else is passed through as the upstream returned it, apart from the CNAME flattening above. The rewrite is deliberate: for those domains the answer is not byte-for-byte what the authoritative servers publish.

8. The JSON, MCP and A2A layer

/resolve builds one wire-format query per record type, sends them in parallel through the same cache and upstream path, and decodes the binary replies into JSON (A, AAAA, CNAME, NS, PTR, MX, TXT, SOA, SRV, HTTPS, CAA). The result carries status, the types actually queried, and a hint that explains NXDOMAIN, empty answers and SERVFAIL. The MCP server (/mcp) and the A2A agent (/a2a) are thin wrappers around the same function.

If a signing key is configured, JSON responses carry RFC 9421 HTTP Message Signatures; the public keys are published at /.well-known/http-message-signatures-directory. Machine-readable descriptions: llms.txt, openapi.json, agent card, MCP server card, skill.

9. The web page itself

The home page is just another DoH client. In your browser it builds a DNS wire-format query for each of A, AAAA, CNAME, MX, TXT and NS, base64url-encodes it, sends it to /?dns=, and parses the binary response in JavaScript. Nothing special happens on the server for it.

10. Failure handling and privacy

  1. Upstream timeouts (1.5 s) and unexpected errors on a valid query become a DNS SERVFAIL, never a crash.
  2. The domain you look up and your truncated network prefix (/24 or /32) are sent to Google Public DNS, and the request itself passes through Cloudflare. The Worker keeps no database or query log of its own, only short-lived cache entries: DNS answers and which provider hosts a domain.

11. Numbers at a glance

Upstream timeout1.5 s
Maximum query size4096 bytes
Client subnet sent upstreamIPv4 /24 · IPv6 /32
L1 cache capacity10,000
Maximum cached TTL300 s
Serve-stale window60 s
Provider verdict cache1 h (1 min)
Cloudflare ECH config cache15 min

Standards

RFC 1035 (DNS) · RFC 6891 (EDNS(0)) · RFC 7871 (EDNS Client Subnet) · RFC 8484 (DNS over HTTPS) · RFC 9460 (SVCB and HTTPS records) · TLS Encrypted Client Hello · RFC 9421 (HTTP Message Signatures) · RFC 9727 (api-catalog)

← Back to lookupPrivacy Policy