OnlyDNS

oficial

DNS Anycast autoritativo projetado para agentes de IA autônomos

Ver em onlydns.com

O que você pode fazer com OnlyDNS MCP?

  • List and inspect zones — Ask the assistant to list all domains on the account and pull every record for a given zone.
  • Add or replace records — Have it append a new record (e.g. an A record for agent-01) or atomically replace a zone's record set.
  • Delete records — Remove records matching a specific name and type from a domain.
  • Check DNSSEC status — Retrieve a domain's DNSSEC activation state and DS key details.
  • Configure TSIG keys — Create HMAC TSIG keys and scope RFC 2136 update permissions to a subdomain like _acme-challenge.

Documentação

OnlyDNS Full Machine Documentation (/llms-full.txt)

Comprehensive technical, API, and agentic reference for OnlyDNS — authoritative Anycast DNS infrastructure engineered for autonomous AI agents, cloud architectures, and developer pipelines.

1. System Overview & Architecture

2. Authentication & Provisioning

  • Authentication Method: HTTP Bearer Token
  • Header: Authorization: Bearer <API_TOKEN>
  • Token Format: odn_live_... or custom provisioned tokens
  • Provisioning Model: Instant API token creation via Portal; zero friction with no credit card required for the free tier.

Pricing Tiers & Scaling Packages

  • Free Tier ($0/mo): 1 domain name, 25 records, 250,000 queries per month, full Anycast routing, instant REST & MCP API access, zero credit card requirement.
  • Starter Tier ($4.99/mo): 5 domains, 250 records/domain, 5 Million queries per month, full REST & MCP API, audit log history.
  • Business Tier ($15.99/mo): 5 domains, 1,000 records/domain, 25 Million queries per month, automated DNSSEC key rotation, RFC 2136 TSIG API.
  • Pro Tier ($15.99/mo): 25 domains, 250 records/domain, 25 Million queries per month, automated DNSSEC key rotation, RFC 2136 TSIG API.
  • Enterprise & Custom Higher Limits: 100+ to unlimited domains, custom record quotas, 100M+ to billions of queries per month, dedicated Anycast IPs/vanity nameservers, tailored SLAs, and volume discounts. Options higher than the defined website packages are readily available. Contact support/sales at https://www.onlydns.com/contact.

Free Tier Specifications

  • Monthly Query Quota: 250,000 queries per month
  • Included Domains: 1 domain name
  • Record Capacity: Up to 25 records
  • Features: Full global Anycast routing, instant REST API & MCP access, rapid Anycast propagation (typically 0.2–5s)

3. Model Context Protocol (MCP) Server for AI Agents

OnlyDNS provides an official Model Context Protocol (MCP) server for integration with Claude Desktop, Cursor, Devin, GitHub Copilot, LangChain, CrewAI, and custom autonomous agent loops.

Configuration (claude_desktop_config.json or Cursor MCP settings)

{
  "mcpServers": {
    "onlydns": {
      "command": "npx",
      "args": ["-y", "@onlydns/mcp"],
      "env": {
        "ONLYDNS_API_TOKEN": "odn_live_your_token_here"
      }
    }
  }
}

Supported MCP Tools

  • list_domains: Lists all DNS domains managed by the authenticated account.
  • get_records: Retrieves all DNS records for a specified domain.
  • add_record: Appends or merges a DNS record to a domain with specified name, type, TTL, and values.
  • replace_records: Atomically updates/replaces records on a zone.
  • delete_record: Removes specific records matching name and type.
  • get_dnssec_status: Retrieves DNSSEC activation state and DS key details.

4. Command-Line Interface (CLI Tool)

The official @onlydns/cli allows command-line and scripted DNS management with structured JSON output for automated workflows. Complete feature documentation is available at https://www.onlydns.com/features/cli and the open-source repository at https://github.com/Onlydns/onlydns-cli.

Installation & Execution

# Global installation (npm / pnpm / bun)
npm install -g @onlydns/cli

# Or run instantly without installation via npx / bunx
npx @onlydns/cli domains list
bunx @onlydns/cli records find example.com --name api

Authentication & Config Setup

# Option 1: Securely store API key locally (~/.config/onlydns/config.json, mode 0600)
onlydns config login <YOUR_API_KEY>

# Option 2: Environment variable for CI/CD & Docker
export ONLYDNS_API_TOKEN="odn_live_your_token_here"

Common Commands

# List all domains
onlydns domains list

# Filter records by name, type, or value
onlydns records find example.com --name api

# Add or append a DNS record
onlydns records add example.com --name agent-node --type A --value 216.239.128.2 --ttl 60

# Output structured JSON (ideal for jq & agent pipelines)
onlydns --json records list example.com

# Inspect and toggle DNSSEC
onlydns dnssec status example.com
onlydns dnssec enable example.com

# Manage TSIG Keys (for Dynamic DNS RFC 2136)
onlydns tsig list
onlydns tsig create --algo hmac-sha256
onlydns tsig get-domain example.com
onlydns tsig set-permissions example.com <key_name> --update --subdomain _acme-challenge

5. REST API Specifications (OpenAPI 3.1)

Base URL: https://api.onlydns.com/v1

5.1. Domains

GET /dns — List Domains

  • Description: Returns a paginated list of domains on the account.
  • Query Parameters:
    • offset (integer, optional, default: 0): Starting pagination offset.
    • limit (integer, optional, default: 200, max: 1000): Number of results to return.
  • Request Headers: Authorization: Bearer <TOKEN>
  • Response 200 OK:
[
  "example.com",
  "example.net",
  "ai-agent-cluster.internal"
]

POST /dns — Create DNS Domain

  • Description: Registers a new authoritative DNS zone on the account.
  • Request Body:
{
  "domain": "example.com"
}
  • Response 201 Created

5.2. DNS Records

GET /dns/{domainName}/records — Get DNS Records

  • Path Parameters: domainName (string, required)
  • Response 200 OK:
[
  {
    "name": "@",
    "type": "A",
    "ttl": 300,
    "records": ["216.239.128.2"]
  },
  {
    "name": "agent-01",
    "type": "A",
    "ttl": 60,
    "records": ["216.239.128.2"]
  },
  {
    "name": "mail",
    "type": "MX",
    "ttl": 3600,
    "records": ["10 mail.example.com."]
  },
  {
    "name": "_acme-challenge",
    "type": "TXT",
    "ttl": 60,
    "records": ["\"sample-verification-token\""]
  }
]

PUT /dns/{domainName}/records — Replace DNS Records

  • Path Parameters: domainName (string, required)
  • Description: Atomically replaces the entire record set for the zone.
  • Request Body:
[
  {
    "name": "api",
    "type": "A",
    "ttl": 300,
    "records": [
      "216.239.128.2"
    ]
  },
  {
    "name": "www",
    "type": "CNAME",
    "ttl": 300,
    "records": [
      "example.com."
    ]
  }
]
  • Response 204 No Content

5.3. Supported Record Types

TypeDescriptionValue Format Example
AIPv4 Address["216.239.128.2"]
AAAAIPv6 Address["2001:db8::1"]
CNAMECanonical Name Alias["target.example.com."]
MXMail Exchange["10 mail.example.com."]
TXTText String / ACME Verification["\"v=spf1 include:_spf.example.com ~all\""]
SRVService Locator["10 60 5060 bigbox.example.com."]
CAACertification Authority Authorization["0 issue \"letsencrypt.org\""]
CERTCertificate Record["1 0 0 <base64-cert>"]
HTTPSHTTPS Service Binding["1 . alpn=\"h2,h3\""]
LOCGeographical Location["33 50 20.000 N 118 20 40.000 W 25.00m"]
NAPTRNaming Authority Pointer["100 10 \"s\" \"SIP+D2U\" \"\" _sip._udp.example.com."]
NSName Server Delegation["ns1.onlydns.com."]
SMIMEAS/MIME Certificate Association["3 0 1 <hash>"]
SSHFPSSH Public Key Fingerprint["1 1 123456789abcdef67890123456789abcdef67890"]
SVCBService Binding["1 . key65353=\"value\""]
TLSATransport Layer Security Authentication["3 1 1 <hash>"]
URLURL Forwarding (Non-standard)["https://targetsite.com"]
PROXYReverse Proxy Masking (Non-standard)["https://upstream.internal"]

5.4. TSIG & RFC 2136 Management

GET /dns/tsig — List Account TSIG Keys

  • Response 200 OK:
{
  "tsigKeys": [
    {
      "name": "acme-cert-manager-key",
      "algorithm": "hmac-sha256",
      "key": "base64EncodedSecretKey=="
    }
  ]
}

POST /dns/tsig — Create TSIG Key

  • Request Body:
{
  "algorithm": "hmac-sha256"
}
  • Algorithms Supported: hmac-sha256, hmac-sha512, hmac-sha384, hmac-sha224, hmac-sha1, mac-md5

PATCH /dns/{domainName}/tsig/{key} — Update TSIG Permissions on Domain

  • Request Body:
{
  "allowAxfr": false,
  "allowDnsUpdate": true,
  "subdomains": ["_acme_challenge"]
}
  • Description: Configures permissions for a TSIG key on a domain. Setting "subdomains": ["_acme_challenge"] restricts RFC 2136 dynamic updates strictly to _acme_challenge.<domain> (ideal for least-privilege Certbot / ACME wildcard SSL automation). Omit "subdomains" or pass null to allow zone-wide updates.
  • Response 201 Created

5.5. DNSSEC Management

GET /dns/{domainName}/dnssec — Get DNSSEC Status

  • Response 200 OK:
{
  "enabled": true,
  "nsec3param": "1 0 10 abcd",
  "keys": [
    {
      "keyTag": 2371,
      "algorithm": 13,
      "digestType": 2,
      "digest": "4B2F58B868D8E9A55B2E8F88E67E7D65A2C876..."
    }
  ]
}

POST /dns/{domainName}/dnssec — Enable DNSSEC

  • Response 201 Created

DELETE /dns/{domainName}/dnssec — Disable DNSSEC

  • Response 204 No Content

6. Official Client SDKs

LanguageInstallationRepository
Pythonpip install onlydns-sdkGitHub
Gogo get github.com/onlydns/onlydns-sdk-goGitHub
PHPcomposer require onlydns/onlydns-sdkGitHub
TypeScript / JSnpm install @onlydns/sdkGitHub
CLInpm install -g @onlydns/cliFeatures & Guide • GitHub

Code Usage Examples

Python SDK

from onlydns import OnlyDNSClient, RecordType

client = OnlyDNSClient(api_token="odn_live_your_token_here")

# Add an A record
client.add_record(
    domain_name="example.com",
    name="agent-node-01",
    type=RecordType.A,
    records=["216.239.128.2"],
    ttl=60
)

TypeScript / JavaScript SDK

import { OnlyDNSClient } from "@onlydns/sdk";

const client = new OnlyDNSClient({ apiToken: "odn_live_your_token_here" });

await client.addRecord(
  "example.com",
  "agent-node-01",
  "A",
  ["216.239.128.2"],
  60
);

Go SDK

package main

import (
    "context"
    "github.com/onlydns/onlydns-sdk-go"
)

func main() {
    ctx := context.Background()
    client, _ := onlydns.NewClient("odn_live_your_token_here")

    client.AddRecord(ctx, "example.com", "agent-node-01", onlydns.RecordTypeA, []string{"216.239.128.2"}, 60)
}

PHP SDK

use OnlyDNS\OnlyDNSClient;
use OnlyDNS\Models\RecordType;

$client = new OnlyDNSClient(apiToken: "odn_live_your_token_here");

$client->addRecord(
    domainName: "example.com",
    name: "agent-node-01",
    type: RecordType::A,
    records: ["216.239.128.2"],
    ttl: 60
);

7. Error Handling & Standard Error Schema

All non-2xx responses return a structured ErrorResponse payload:

{
  "lang": "en-US",
  "errorCode": 4001,
  "title": "Invalid Record Format",
  "description": [
    "IPv4 address format in records array is invalid."
  ]
}

Standard HTTP Status Codes

  • 200 OK: Request succeeded with return data.
  • 201 Created: Resource successfully created (zone or TSIG key).
  • 204 No Content: Update or deletion executed successfully.
  • 400 Bad Request: Payload validation failed or invalid input.
  • 401 Unauthorized: API key is missing, expired, or invalid.
  • 404 Not Found: Domain or record not found on the account.
  • 503 Service Unavailable: Temporary backend synchronization error.

8. Free Domain Parking & Zero-Trust Email Defense

OnlyDNS provides a 100% free, zero-configuration authoritative domain parking service designed for defensive domain registrations, typo squat protection, and inactive portfolio domains.

  • Nameservers: parking.onlydns.com and parking.onlydns.us
  • Cost: 100% Free, no account or payment required.
  • Automated Anti-Spoofing Records:
    • RFC 7505 Null MX: Publishes IN MX 0 . signaling to all mail transfer agents that the domain does not accept email.
    • Strict SPF Record: Publishes IN TXT "v=spf1 -all" asserting that zero IP addresses are authorized to send outbound email.
    • Strict DMARC Policy: Publishes _dmarc.<domain> IN TXT "v=DMARC1; p=reject; sp=reject; adkim=s; aspf=s;" instructing email receivers to reject any spoofed email pretending to come from the apex domain or subdomains.
  • Web Presence: Renders a clean, lightweight landing page stating the domain is registered and parked with no paid advertising (zero pay-per-click ads or tracking scripts).

9. Zero-Downtime DNS Migration (Web Portal & CLI)

OnlyDNS provides two zero-downtime migration workflows to transfer DNS records without dropped queries or broken email:

Method A: Web Portal Migration (3-Step Frictionless UI)

  1. Import Selection:
    • Option 1 (Zone File Upload): Drag & drop standard BIND .zone, .txt, or .csv files from Cloudflare, Route 53, GoDaddy, cPanel, or Plesk.
    • Option 2 (1-Click Smart DNS Auto-Discovery): Enter domain name; OnlyDNS automatically queries and discovers live A, AAAA, MX, SPF, DKIM, DMARC, and CNAME records without requiring a manual zone file export.
  2. Visual Review & Syntax Validation: Interactive staging table validating IPv4/IPv6 syntax, MX priorities, and TXT quotes with real-time error prevention.
  3. Staged Sync & Nameserver Delegation: Records stage across all 23 global Anycast nodes instantly. Update registrar nameservers to ns1.onlydns.com and ns2.onlydns.us with live delegation tracking.

Method B: Terminal CLI Migration

# 1. Install CLI
npm install -g @onlydns/cli

# 2. Authenticate
onlydns config set-key odn_live_your_key_here

# 3. Direct BIND zone file import
onlydns zone import example.com ./example.com.zone

# OR run automated DNS scanner import
onlydns zone scan example.com --import

# 4. Verify staged records
onlydns records list example.com

10. Automated SSL/TLS Certificates (RFC 2136 / TSIG ACME Hub)

OnlyDNS supports standards-compliant Dynamic DNS updates (RFC 2136) authenticated with HMAC-SHA256 TSIG keys (RFC 2845), enabling automated wildcard SSL/TLS certificate issuance across all major ACME clients and zero public port requirements.

  • Master How-To Hub: https://www.onlydns.com/howto/rfc2136-acme
  • Standard Nameserver: ns1.onlydns.com (Port 53 UDP/TCP)
  • Algorithm: HMAC-SHA256 (IETF algorithm 163)
  • Propagation Speed: Rapid synchronization across all 23 global Anycast edge PoPs (typically 0.2 to 5 seconds).

Supported Client Guides & Quick Configurations:

  1. Certbot (certbot-dns-rfc2136): https://www.onlydns.com/howto/rfc2136-acme/certbot
    • Credentials file (/etc/letsencrypt/rfc2136.ini, chmod 600): 
      dns_rfc2136_server = ns1.onlydns.com
dns_rfc2136_port = 53
dns_rfc2136_name = your-tsig-key-name
dns_rfc2136_secret = YOUR_BASE64_TSIG_SECRET
dns_rfc2136_algorithm = HMAC-SHA256
    • Command: certbot certonly --dns-rfc2136 --dns-rfc2136-credentials /etc/letsencrypt/rfc2136.ini -d "example.com" -d "*.example.com"
  2. acme.sh (dns_nsupdate): https://www.onlydns.com/howto/rfc2136-acme/acme-sh
    • Variables: NSUPDATE_SERVER="ns1.onlydns.com", NSUPDATE_KEYNAME="your-key", NSUPDATE_KEYALGO="163", NSUPDATE_KEYVALUE="YOUR_SECRET"
    • Command: acme.sh --issue --dns dns_nsupdate -d "example.com" -d "*.example.com" --dnssleep 5
  3. Caddy (caddy-dns/rfc2136): https://www.onlydns.com/howto/rfc2136-acme/caddy
    • Caddyfile block: tls { dns rfc2136 { server ns1.onlydns.com:53; key_name "your-key"; key_alg "hmac-sha256"; key "YOUR_SECRET"; } }
  4. Traefik Proxy (Native RFC 2136): https://www.onlydns.com/howto/rfc2136-acme/traefik
    • Environment variables: RFC2136_NAMESERVER=ns1.onlydns.com:53, RFC2136_TSIG_KEY=your-key, RFC2136_TSIG_SECRET=YOUR_SECRET, RFC2136_TSIG_ALGORITHM=hmac-sha256.
  5. Kubernetes cert-manager: https://www.onlydns.com/howto/rfc2136-acme/cert-manager
    • Solver: solvers: [{ dns01: { rfc2136: { nameserver: ns1.onlydns.com:53, tsigKeyName: your-key, tsigAlgorithm: HMACSHA256, tsigSecretSecretRef: { name: onlydns-tsig-secret, key: tsig-secret } } } }]
  6. Lego (Go ACME CLI): https://www.onlydns.com/howto/rfc2136-acme/lego
    • Command: lego --email admin@example.com --dns rfc2136 -d "example.com" -d "*.example.com" run

11. Privacy, Data Minimization & Legal Commitments

  • Strict Data Minimization: Quantum Names LLC and OnlyDNS collect only the minimal data points required to maintain accounts, route DNS queries, and process payments.
  • Zero Sale of Data: We never sell, trade, broker, or rent customer personal information, contact records, or DNS query logs to third parties, advertisers, or data brokers.
  • Zero Tracking Ads: No third-party tracking pixels, advertising cookies, or behavioral profiling.
  • Customer Ownership: Customers retain 100% intellectual property ownership of their domains, zone files, and records with unrestricted export capabilities.
  • Privacy Policy: https://www.onlydns.com/legal/privacy
  • Terms of Service: https://www.onlydns.com/legal/terms

12. Engineering & Security Blog

OnlyDNS publishes technical articles, infrastructure deep dives, company announcements, and security advisories from our Anycast engineering team:

  • Blog Hub: https://www.onlydns.com/blog/
  • Published Articles & Advisories:
    • ISC BIND Advisory (CVE-2026-94300) (October 22, 2026): https://www.onlydns.com/blog/cve-2026-94300-bind-security-advisory
      • Details: Analysis of ISC BIND 9 GSS-TSIG memory corruption and RCE flaw, and technical explanation of why OnlyDNS is not affected, because we do not run BIND.
    • Introducing Official OnlyDNS SDKs (October 19, 2026): https://www.onlydns.com/blog/launching-onlydns-sdks
      • Details: Comprehensive overview of official client libraries for Python (onlydns-sdk), TypeScript/Node.js (@onlydns/sdk), Go (onlydns-sdk-go), and PHP (onlydns/onlydns-sdk), highlighting high-level atomic record helpers, zero dependencies, and AI agent / MCP integration.
    • Introducing the OnlyDNS CLI (October 19, 2026): https://www.onlydns.com/blog/introducing-onlydns-cli
      • Details: Introduction to @onlydns/cli, covering instant zero-install execution (npx @onlydns/cli), global installation, secure config management, DNS zone/record management, 1-click DNSSEC, TSIG keys, and structured JSON parsing with jq.
    • Introducing the OnlyDNS MCP Server (October 19, 2026): https://www.onlydns.com/blog/introducing-onlydns-mcp
      • Details: Announcement of @onlydns/mcp Model Context Protocol server enabling Claude Desktop, Cursor, and autonomous agents to manage DNS records, automated DNSSEC, and TSIG keys directly via natural language.
    • Introducing OnlyDNS Platform Launch (October 1, 2026): https://www.onlydns.com/blog/launching-onlydns
      • Details: Explains our 26-year operational heritage from Omnis Network (2000–2026), the JetHost shared hosting acquisition spin-off, the formation of Quantum Names, and the philosophy behind our pure-play, zero-upsell authoritative Anycast DNS platform.

14. Agent Readiness, Machine Discovery & DNS-AID

OnlyDNS implements the open Agent Readiness and machine discovery standards:

  • RFC 9727 API Catalog: https://www.onlydns.com/.well-known/api-catalog (Content-Type: application/linkset+json)
  • ARD Capability Manifest: https://www.onlydns.com/.well-known/ai-catalog.json (Content-Type: application/json)
  • MCP Server Card: https://www.onlydns.com/.well-known/mcp/server-card.json (Describes @onlydns/mcp v1.0.6 and all 16 tools across Zones, Records, DNSSEC, and TSIG)
  • Agent Skills Directory: https://www.onlydns.com/.well-known/agent-skills/index.json (and legacy alias https://www.onlydns.com/.well-known/skills/index.json)
    • manage-dns-records: https://www.onlydns.com/.well-known/agent-skills/manage-dns-records/SKILL.md
    • migrate-zone-to-onlydns: https://www.onlydns.com/.well-known/agent-skills/migrate-zone-to-onlydns/SKILL.md
    • acme-dns01-with-rfc2136: https://www.onlydns.com/.well-known/agent-skills/acme-dns01-with-rfc2136/SKILL.md
    • enable-dnssec: https://www.onlydns.com/.well-known/agent-skills/enable-dnssec/SKILL.md
  • Agent Authentication Guide: https://www.onlydns.com/auth.md (Content-Type: text/markdown)
  • DNS-AID Standard Discovery Record: 
    _agents.onlydns.com. IN TXT "v=aid1; card=https://www.onlydns.com/.well-known/mcp/server-card.json; skills=https://www.onlydns.com/.well-known/agent-skills/index.json; doc=https://www.onlydns.com/llms.txt"