agentic-dns MCP server
Commit Nov 1, 2026Manages a complete DNS resolution chain and provides telemetry, diagnostics, and routing control for autonomous agents.
Also known as dedsecorg/agentic-dns
- Stars
- 8
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 1, 2026
- License
- MIT
What is agentic-dns MCP?
agentic-dns manages a complete DNS resolution chain and provides telemetry, diagnostics, and routing control for autonomous agents.
Summary generated from the project's README
About agentic-dns MCP server
Managing complex DNS resolution chains is what agentic-dns enables for developers building autonomous agents. It provides a way to oversee a multi-layered infrastructure including Pi-hole, CoreDNS, dnsdist, Unbound, Stubby, and DNSCrypt. By treating the DNS chain as managed infrastructure, it allows agents to discover network topology, perform health checks on every hop, and automatically reconfigure upstreams when VPN endpoints like ProtonVPN, NordVPN, or Tailscale change.
Users can interact with the system via a CLI, a REST API requiring mTLS authentication, or a stdio MCP server. The setup is designed for Linux environments and relies on pure POSIX Bash and standard Unix tools without Python or Node dependencies. For enhanced security, a dedicated Rust-based DoT/mTLS proxy server can be used to terminate TLS and forward queries to the local chain. This makes it ideal for ephemeral agent sandboxes or headless runners that require reliable, traceable, and intercepted DNS resolution.
What you can do with it
- 1Diagnose DNS resolution failuresAn AI agent can trace the exact path of a DNS query through every hop in the chain to find where resolution breaks.
- 2Monitor network service healthA developer can task an agent with checking the operational status and configuration of all active DNS services.
- 3Automate DNS routing updatesAgents can dynamically add or remove upstream routing rules in dnsdist to maintain connectivity.
- 4Intercept encrypted mobile trafficAn agent can enforce DNS interception for mobile devices to ensure all encrypted queries pass through Pi-hole.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablededsecorg/agentic-dns is public and reachablegithub.com/dedsecorg/agentic-dns ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-01github.com/dedsecorg/agentic-dns ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubagentic-dns
Agentic AI-Native DNS Routing, Diagnostics & Telemetry. Manages a complete DNS resolution chain (Pi-hole -> CoreDNS -> dnsdist -> Unbound/Stubby/DNSCrypt -> VPN DNS) with CLI, REST API, stdio MCP, and a Rust DoT/mTLS proxy server. Pure POSIX Bash + standard Unix tools -- zero Python/Node dependencies.
OCI Container (GHCR)
Pre-built multi-architecture images (linux/amd64, linux/arm64) for ephemeral agent sandboxes and headless runners.
Pulling the Image
# Pinned release
docker pull ghcr.io/dedsecorg/agentic-dns:1.6.0
# Moving major release
docker pull ghcr.io/dedsecorg/agentic-dns:v1
# Latest tracking branch
docker pull ghcr.io/dedsecorg/agentic-dns:latest
Running the Resolver Health & Trace Tools
# Quick health check
docker run --rm \
--cap-add=NET_ADMIN \
ghcr.io/dedsecorg/agentic-dns:v1 status
# Run trace check against host resolver
docker run --rm \
--cap-add=NET_ADMIN \
--network=host \
ghcr.io/dedsecorg/agentic-dns:v1 trace api.anthropic.com
Context7 Documentation
This repository is indexed on Context7 with 134 code snippets for AI-assisted development. Use the Context7 MCP server or visit the link above for searchable documentation.
# Query via Context7 MCP
# "How to install agentic-dns?"
# "agentic-dns commands reference"
# "DNS chain architecture"
Why This Exists
Modern networks run multiple DNS layers simultaneously: Pi-hole for blocking, CoreDNS for split-horizon, dnsdist for load balancing, Unbound for recursive resolution, Stubby/DNSCrypt for DoT/DoH, plus VPN-provided DNS. When any layer fails or VPNs rotate DNS, resolution breaks silently.
agentic-dns treats the DNS chain as managed infrastructure:
- Discovers topology -- detects running services, VPN DNS endpoints, listening ports
- Health-checks each hop -- active DNS queries against every resolver
- Auto-reconfigures -- rewrites dnsdist/CoreDNS upstreams when VPN DNS changes
- Exposes telemetry -- REST API, MCP server, structured logs for AI agents
- Provides DoT/mTLS proxy -- Rust server terminates TLS, forwards to chain
Architecture
+------------------+
| Client Query |
+--------+---------+
|
v
+------------------+
| Pi-hole (53) | -- blocking, cache
| forwarder |
+--------+---------+
|
v
+------------------+
| CoreDNS (5352) | -- split-horizon, local zones
+--------+---------+
|
v
+------------------+
| dnsdist (5330) | -- load balance, retry, Lua policy
+--------+---------+
+--------+--------+--------+
| | |
v v v
+------------+ +------------+ +------------+
| Unbound | | Stubby | | DNSCrypt |
| (5335) | | (5360) | | (5354) |
| recursive | | DoT proxy | | DoH proxy |
+-----+------+ +-----+------+ +-----+------+
| | |
+--------+--------+----------------+
|
v
+------------------+
| VPN DNS | -- discovered dynamically
| (Proton/Nord/ |
| Tailscale) |
+------------------+
+------------------+
| agentic-dns- | -- Rust DoT/mTLS proxy
| server (853) | on 127.0.0.1 or Tailscale
+------------------+
Installation
Manual
git clone https://github.com/dedsecorg/agentic-dns
cd agentic-dns
sudo -S -p '' -S -p '' ./install.sh
Installs:
/usr/local/bin/agentic-dns-- main CLI/usr/local/bin/agentic-dns-server-- Rust DoT/mTLS proxy (prebuilt or cargo build)/etc/agentic-dns/-- configs for dnsdist, CoreDNS, Unbound, Stubby, DNSCrypt/etc/systemd/system/agentic-dns.service-- systemd unit/etc/systemd/system/agentic-dns-server.service-- Rust server unit
Smithery (for MCP clients)
npx -y @smithery/cli install @dedsecorg/agentic-dns
Commands
| Command | Description |
|---|---|
agentic-dns status |
Show all DNS services, addresses, types, health |
agentic-dns query <domain> |
Resolve through full chain |
agentic-dns trace <domain> |
Trace DNS path with live packet capture at each hop |
agentic-dns routes |
List Pi-hole upstreams (from pihole.toml) and current dnsdist routing rules |
agentic-dns route add <name> <addr:port> |
Add upstream to dnsdist |
agentic-dns route remove <name> |
Remove upstream from dnsdist |
agentic-dns bypass <service> [backup] |
Bypass failing service (auto-switch to backup) |
agentic-dns enforce {on,off,status,clean} [ip] |
Intercept phone encrypted DNS -> Pi-hole |
agentic-dns pihole-log |
Show recent Pi-hole DNS query log |
agentic-dns health |
Check health of all DNS services |
agentic-dns tag |
Show service tags |
agentic-dns api |
Start REST API server on port 8099 |
agentic-dns mcp |
Start stdio MCP JSON-RPC server |
agentic-dns server |
Start Rust DoT/mTLS proxy server |
DNS Chain Services
| Service | Port | Role | Upstream |
|---|---|---|---|
| Pi-hole | 53 | Blocking, cache, DHCP | CoreDNS |
| CoreDNS | 5352 | Split-horizon, local zones | dnsdist |
| dnsdist | 5330 | Load balancer, Lua policy | Unbound, DNSCrypt |
| Unbound | 5335 | Recursive resolver | VPN DNS |
| Stubby | 5360 | DoT proxy (TLS) | VPN DNS |
| DNSCrypt | 5354 | DoH proxy | Cloudflare/Quad9 DoH |
| agentic-dns-server | 853 | DoT/mTLS proxy (Rust) | Chain entry |
VPN DNS Discovery
Automatically detects VPN DNS endpoints:
- ProtonVPN --
protonvpn statusor NetworkManagerproton0interface - NordVPN -- WireGuard config or
nordvpn status - Tailscale --
tailscale status --jsonmagic DNS - WireGuard --
wg showallowed IPs
Set manually: VPN_DNS=10.2.0.1 agentic-dns status
Configuration
/etc/agentic-dns/ -- Service Configs
Generated by install.sh, editable for custom zones/upstreams:
dnsdist.conf-- routing rules, load balancing, Lua policiesCorefile-- CoreDNS zones, pluginsunbound.conf-- recursive resolver settingsstubby.yml-- DoT upstream certificatesdnscrypt-proxy.toml-- DoH server stamps
Environment Variables
| Variable | Default | Description |
|---|---|---|
PIHOLE_HOST |
127.0.0.1 | Pi-hole API address |
PIHOLE_API_KEY |
/etc/pihole/pihole-api-key.txt | Pi-hole API key |
AGENTIC_DNS_API_PORT |
8099 | REST API port |
AGENTIC_DNS_TLS_CERT |
/etc/agentic-dns/certs/api.crt | REST API server cert (mTLS) |
AGENTIC_DNS_TLS_KEY |
/etc/agentic-dns/certs/api.key | REST API server key |
AGENTIC_DNS_TLS_CA |
/etc/agentic-dns/certs/ca.crt | CA that client certs must chain to |
VPN_DNS |
auto | Override VPN DNS |
AGENTIC_DNS_SERVER_BIN |
agentic-dns-server | Rust server binary |
MCP Integration
Start read-write MCP server:
agentic-dns mcp
Tools exposed:
dns_status-- all services health + configdns_query-- resolve domain through chaindns_trace-- packet capture at each hopdns_route_add-- add dnsdist upstreamdns_route_remove-- remove dnsdist upstreamdns_bypass-- failover servicedns_enforce-- phone DNS interceptiondns_pihole_log-- Pi-hole query log
REST API
The API is mTLS-only: socat terminates TLS 1.3 and requires a client cert
signed by ca.crt before the handler runs. See docs/pki.md
for generating the CA, server and per-agent client certs with openssl.
agentic-dns api
# or
curl --cacert /etc/agentic-dns/certs/ca.crt --cert agent.crt --key agent.key \
https://localhost:8099/api/v1/status
Endpoints (all read-only; responses are {"status":"ok","text":"..."}):
GET /api/v1/status-- full service statusGET /api/v1/health-- health checksGET /api/v1/routes-- Pi-hole upstreams (pihole.toml) and dnsdist upstreamsGET /api/v1/query?domain=example.com-- resolveGET /api/v1/trace?domain=example.com-- traceGET /api/v1/pihole/log-- Pi-hole logs
Mutations (route add/remove, bypass, enforce) are CLI/MCP-only and are
deliberately not exposed over the network.
Phone DNS Interception (Android)
# On server (run as root)
agentic-dns enforce on 100.87.74.22
# On Android: set DNS to server Tailscale IP (100.74.31.18)
# All DoT (port 853) from phone -> Pi-hole -> chain
Uses nftables/iptables TPROXY + agentic-dns-server DoT proxy to transparently intercept encrypted DNS (port 853) and force through Pi-hole.
Rust DoT/mTLS Server
agentic-dns-server -- standalone binary:
- Terminates TLS on 853 (DoT) or 443 (DoH)
- Requires client certs chaining to
--client-ca(mTLS, mandatory) - Hybrid post-quantum key exchange only (X25519MLKEM768;
--allow-classical-kxto also offer X25519) - Forwards to local DNS chain
- Metrics on
:9090/metrics(Prometheus) - Zero-copy, async, ~2MB RAM
Build:
cd server && cargo build --release
# or download prebuilt from releases
Requirements
- Linux (systemd, nftables/iptables)
- Pi-hole, CoreDNS, dnsdist, Unbound, Stubby, DNSCrypt-Proxy installed
dig,ss,jq,bash4.4+- Rust 1.75+ (for server build)
CAP_NET_ADMIN,CAP_NET_BIND_SERVICE(for server)
License
MIT -- see LICENSE.
Related
- agentic-route -- kernel policy routing reconciler (same author)
- hermes-dns -- private fork with real IPs, same engine# Test payment notification test test2 test3
agentic-dns MCP questions
Does it support VPN DNS discovery?
Yes, it automatically detects VPN DNS endpoints for services like ProtonVPN, NordVPN, Tailscale, and WireGuard.