MeshDNS API Reference

Complete reference for the MeshDNS REST API. All endpoints return JSON. The API is versioned under /v0.

API Endpoints

GET /v0/resolve?capability=X

Resolve servers by capability. Returns only healthy (UP) servers, ordered by uptime.

Param	Description
capability required	The capability slug to resolve (e.g. "sandbox", "web-search", "mcp-server")

curl -s "https://provengraph.trucore.xyz/v0/resolve?capability=sandbox" | jq .

GET /v0/servers

List servers with filters and cursor-based pagination.

Param	Description
query	Full-text search across name and description
capability	Filter by capability slug
status	active (default), delisted, or all
cursor	Pagination cursor from previous response
limit	Max results per page (1–100, default 20)

curl -s "https://provengraph.trucore.xyz/v0/servers?capability=mcp-server&status=active&limit=10" | jq .

GET /v0/servers/{id}

Get a single server by its UUID.

curl -s "https://provengraph.trucore.xyz/v0/servers/00047d75-8270-42f4-b79d-e3fc30db4510" | jq .

POST /v0/servers

curl -X POST https://provengraph.trucore.xyz/v0/servers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-mcp-server",
    "description": "My custom MCP server providing sandbox execution",
    "server_url": "https://my-server.example.com",
    "health_url": "https://my-server.example.com/health",
    "probe_method": "GET",
    "capabilities": ["sandbox", "code-execution"],
    "owner_contact": "ops@example.com"
  }'

PUT /v0/servers/{id}

Update server manifest. Requires X-Write-Key or Authorization: Bearer header. All fields are optional — send only what changed.

curl -X PUT https://provengraph.trucore.xyz/v0/servers/{id} \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: {your_write_key}" \
  -d '{"description": "Updated description"}'

DELETE /v0/servers/{id}

Delist (soft-delete) a server. Requires write key auth. The server is hidden from list/resolve but retained for history.

curl -X DELETE https://provengraph.trucore.xyz/v0/servers/{id} \
  -H "X-Write-Key: {your_write_key}"

GET /v0/stats

Registry statistics: active/total servers, up count, 24h resolutions and probe counts.

curl -s "https://provengraph.trucore.xyz/v0/stats" | jq .

GET /v0/export

Full registry dump — all servers with current health state. Useful for bulk analysis.

curl -s "https://provengraph.trucore.xyz/v0/export" | jq .

Health Checks

GET Probe (default)

MeshDNS sends a GET to health_url every 60s. If the server responds 2xx, it's marked UP. Non-2xx triggers auto-detect POST probe.

POST Probe (auto-detect)

If GET fails with 405 or any 4xx, MeshDNS sends a standards-compliant MCP initialize request. If POST succeeds, the server is marked UP and the switch is persisted.

Explicit POST

Set "probe_method": "POST" when registering to skip the GET attempt entirely. Required for streamable-HTTP MCP endpoints that don't answer GET.

Timeout & Uptime

5s probe timeout. 30-day rolling uptime tracked per server. /v0/resolve never returns DOWN servers. Servers without a health_url are declared healthy by default.

Catalog Sources

MCP Official Registry

5,400+ servers from the official MCP registry. Probed for health with GET + POST auto-detect. Updated via catalog sync.

Smithery

110+ servers from Smithery's registry. Deployment URLs resolved via parallel detail API. Tool names pre-discovered from descriptions.

npm MCP Packages

240+ servers from npm with the mcp-server keyword. GitHub repo URLs extracted, declared healthy.

Manual Registration

SDKs

Python

pip install meshdns-client

from meshdns_client import MeshDNS

client = MeshDNS("https://provengraph.trucore.xyz")
servers = client.resolve("sandbox")
for s in servers:
    print(s["name"], s["server_url"], s["uptime_30d"])

TypeScript

npm i @meshdns/client

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

const client = new MeshDNS("https://provengraph.trucore.xyz");
const servers = await client.resolve("sandbox");
console.log(servers.map(s => s.name));

Hermes Agent Skills

MeshDNS ships with three pre-built Hermes Agent skills for instant agent integration:

meshdns-quickstart — one-stop guide: discover, register, lazy MCP pattern
meshdns — full API reference, architecture, deployment, health checks
meshdns-lazy-mcp — on-the-fly MCP discovery, 750+ servers, zero pre-config

Load with: skill_view('meshdns-quickstart')

Deployment

Single Binary

MeshDNS ships as a single static Go binary with zero external dependencies. SQLite via pure Go — no CGo, no database server needed.

Docker

docker build -t meshdns .
docker run -d -p 8080:8080 -v ./data:/data meshdns

Configuration

MESHDNS_PORT=:8080
MESHDNS_DB=/data/meshdns.db
MESHDNS_PROBE_INTERVAL=60s
MESHDNS_PROBE_TIMEOUT=5s
MESHDNS_WORKERS=10

Systemd

[Service]
ExecStart=/usr/local/bin/meshdns
WorkingDirectory=/var/lib/meshdns
Restart=always
RestartSec=5

Architecture

Stack

Go stdlib HTTP server — no frameworks
SQLite via modernc.org/sqlite — pure Go, file-based
Background health pool — configurable workers
Bearer token auth — write_key per registration

Data Flow

Servers register via POST /v0/servers
Background workers probe health URLs every 60s
Agents query GET /v0/resolve?capability=X
Only UP servers returned, ranked by uptime

Response Format

Every server object includes:

source / source_url — catalog provenance (MCP Registry, Smithery, npm, TruCore)
auth — public, auth-required, or unknown
tool_count / tool_names — tools pre-discovered from descriptions
curl_snippet — ready-to-use lazy MCP call command

llms.txt

LLM-readable API reference at /llms.txt. Targeted at AI agents and coding assistants for programmatic discovery.

Built by TruCore Ventures · GitHub · MIT License