MeshDNS

What is MeshDNS?

MeshDNS is a capability-based service registry for MCP (Model Context Protocol) servers. Think DNS, but for your AI agent mesh. Instead of hardcoding server URLs into every agent config file, agents ask: "who can do weather forecasting right now?" — and MeshDNS returns the best available server.

Every MCP agent today ships a hardcoded JSON server list. New server = config edit. Dead server = silent failure. No way to ask "who can do X?" MeshDNS fixes all three: dynamic registration, live health checks, and capability-based resolution in one MCP-native call.

Architecture

Six components in one static Go binary:

Quickstart

Install, start, register, resolve — 60 seconds:

$ go install github.com/trucore-ai/meshdns/cmd/meshdns@latest
$ meshdns --port=:8080
  MeshDNS listening on :8080

# Register a server
$ curl -s -X POST http://localhost:8080/v0/servers \
  -H "Content-Type: application/json" \
  -d '{"name":"weather-agent","description":"Weather data MCP server",
       "server_url":"https://weather.example.com",
       "health_url":"https://weather.example.com/health",
       "capabilities":["weather","forecast","alerts"],
       "owner_contact":"ops@example.com"}'
# → {"server_id":"...","write_key":"..."}

# Resolve by capability
$ curl -s "http://localhost:8080/v0/resolve?capability=weather"
# → [{"name":"weather-agent","server_url":"https://weather.example.com",...}]

API Reference

How Health Checks Work

MeshDNS probes every registered server's health_url on a configurable interval (default: 60s). A probe is a simple HTTP GET with a 5-second timeout. Non-2xx responses and timeouts both mark the server as DOWN.

1. Register with health_url. When you register a server, provide the health endpoint URL. MeshDNS starts probing it immediately.
2. Probe every 60s. Background goroutine pool sends HTTP GET requests. Configurable via MESHDNS_PROBE_INTERVAL and MESHDNS_PROBE_TIMEOUT env vars.
3. Mark UP/DOWN. Server goes down → marked DOWN within one probe cycle. Server comes back → marked UP on the next successful probe. 30-day uptime history preserved.
4. Resolution excludes DOWN servers. /v0/resolve never returns servers marked DOWN. Agents always get working endpoints. No silent failures.

SDK Reference

Python

$ pip install meshdns-client

from meshdns_client import MeshDNSClient

client = MeshDNSClient("https://meshdns.trucore.xyz")

# Resolve a capability
servers = client.resolve("weather")
# → [{"name":"weather-agent","server_url":"https://...","up":true}]

# Smart retry — skips recently-failed servers
next_server = client.resolve_next("weather")

TypeScript

$ npm i @meshdns/client

import { MeshDNSClient } from "@meshdns/client";

const client = new MeshDNSClient("https://meshdns.trucore.xyz");

// Resolve a capability
const servers = await client.resolve("weather");

// Smart retry — skips recently-failed servers
const next = await client.resolveNext("weather");

Configuration

All config via environment variables:

Security Model

FAQ

How is this different from the MCP Registry?

The official MCP Registry is a flat list of servers with no capability search, no health checks, and no programmatic resolution. MeshDNS adds all three: ask "who can do weather?" and get back working servers sorted by uptime — automatically.

Can I run my own instance?

Yes. MeshDNS is a single Go binary — MIT-licensed, self-contained, zero external dependencies. Deploy behind Caddy or nginx with auto-TLS and you have a private registry in minutes. The public instance at meshdns.trucore.xyz is a convenience, not a requirement.

What happens if MeshDNS goes down?

Agents should cache the last resolve result and fall back to cached servers. Additionally, GET /v0/export gives you the full registry as JSON — archive it periodically for disaster recovery.

How fast is resolution?

p99 under 100ms with 1,000 registered servers on MVP hardware. Resolution is a simple indexed SQLite query — no network hops, no external services, no cache warming.

When will trust scores be added?

Trust scores and ratings are planned for phase 2. They need usage data to be meaningful — the current uptime-based ranking is the v1 foundation that trust scores build on. Register now and your uptime history gives you a head start when scoring launches.

Integrations & Next Steps