DoH

You can run an MCP-enabled DNS over HTTPS (DoH) server that queries multiple DoH providers in parallel, uses a smart consensus to pick the best result, and exposes MCP-compatible APIs for AI models and clients. This setup gives you fast, reliable DNS answers with full MCP tooling and a web UI for debugging and exploration.

How to use

Connect your MCP client to the DoH MCP Server to perform DNS lookups and debugging. Your client can request DNS records for domains using a standard MCP workflow, and you can leverage the server’s parallel querying, multi-provider support, and consensus-based result selection to get accurate answers quickly. Use the provided MCP SSE endpoint for streaming interactions and the HTTP MCP endpoint for request/response style communication. You can also explore debugging data to understand how different providers respond and how consensus is formed.

How to install

Prerequisites: you need Node.js and npm installed on your system.

1. One-click deployment

• Open the deployment workflow and follow the prompts to deploy to Cloudflare Workers using the provided template.

2. CLI deployment

• Run the following command to bootstrap the server with the DoH MCP template.

npm create cloudflare@latest -- my-doh-server --template=https://github.com/Randark-JMT/doh-mcp

3. Local development workflow

• Clone the repository, install dependencies, run the development server, and then deploy to production when ready.

git clone https://github.com/Randark-JMT/doh-mcp.git
cd MCPs/doh-worker
npm install
npm run dev
npm run deploy

Configuration and capabilities

The server provides DoH support across multiple providers, with a DoH server list including DNSPod, Alidns, 360, Google, Cloudflare, Quad9, DNS.SB, OpenDNS, and AdGuard. It supports common DNS record types such as A, AAAA, CNAME, MX, TXT, NS, PTR, SRV, and SOA. You can perform parallel lookups, analyze responses from multiple providers, and select the most consensus-backed result for each query.

Connecting with an MCP client

You can connect using a standard MCP client that supports SSE and HTTP endpoints. The server exposes an SSE endpoint at /sse for streaming MCP communication and a HTTP endpoint at /mcp for request/response interactions. For example, you can connect Claude Desktop or other MCP clients by pointing them to your DoH MCP Server’s SSE URL or HTTP endpoint. Also, you can use a web UI at the root path for interactive DNS querying and debugging.

API and endpoints overview

• Web UI: GET / for the main interface, GET /debug for debugging tools.

• MCP endpoints: POST /sse for MCP SSE connections, GET /sse to initialize, POST /mcp for MCP HTTP protocol.

• REST API: POST /api/dns/lookup and POST /api/dns/debug for DNS queries and debugging.

• Traditional DoH: GET /dns-query for compatibility with classic DoH clients.

DoH servers and record types

DoH providers supported: DNSPod, Alidns, 360, Google, Cloudflare, Quad9, DNS.SB, OpenDNS, AdGuard.

Supported DNS record types: A, AAAA, CNAME, MX, TXT, NS, PTR, SRV, SOA.

Security and reliability notes

The server is designed for robustness with parallel querying, automatic fallback to healthy providers, and detailed error reporting. Timeouts are configurable to balance speed and completeness, and the system gracefully degrades when some providers fail.

Notes

Each MCP client can utilize the SSE endpoint for streaming and the HTTP endpoint for standard requests. When testing locally, use the local development commands and then deploy to production to expose a public DoH MCP service.

Example configuration snippet

{
  "mcpServers": {
    "doh_server": {
      "type": "stdio",
      "name": "doh_server",
      "command": "npx",
      "args": ["mcp-remote", "https://your-doh-server.your-account.workers.dev/sse"]
    }
  }
}

Available tools

dns_lookup

Executes a DNS lookup for a domain and returns the best result using parallel DoH queries and consensus.

dns_debug

Fetches detailed debugging information from multiple DoH providers to troubleshoot issues.

get_doh_servers

Retrieves the list of available DoH servers supported by the MCP server.

dns_record_types

Provides the supported DNS record types and their meanings.