Tutorial
Publish your AI agent to ARD in 10 minutes
Three steps: write one JSON file, advertise it four ways, then verify that registries actually return you, because publishing and being indexed are different things and only one of them gets you found.
Step 1, write the manifest
Serve it at both paths. The specification renamed the file to
/.well-known/ard.json in v0.91, but the ecosystem has not moved: of 178
publishers we have crawled, 157 still serve the older
/.well-known/ai-catalog.json and only 14 serve ard.json.
Registries differ in which they request, so serving the same bytes at both paths is the
only way to be certain you are found. It costs one alias.
One file, served at /.well-known/ard.json.
{
"specVersion": "1.0",
"host": {"displayName": "Example Inc", "identifier": "did:web:example.com"},
"entries": [{
"identifier": "urn:air:example.com:mcp:weather",
"displayName": "Weather API",
"type": "application/mcp-server-card+json",
"url": "https://example.com/.well-known/mcp/server-card.json",
"description": "Current conditions and forecasts for any location.",
"representativeQueries": [
"what is the weather in Berlin",
"will it rain in London tomorrow"
]
}]
}
Or generate it, which validates as you go:
pip install ard-publish python -m ard_publish init example.com > .well-known/ard.json
The identifier is domain-anchored: urn:air:<your-domain>:<namespace>:<name>.
The publisher segment must be a domain you control, because that is what publisher-authority binding
checks.
Step 2, advertise it four ways
A consumer may check any of four paths, and serving only one makes you invisible to clients that check another.
# robots.txt Agentmap: https://example.com/.well-known/ard.json
<!-- in your <head> --> <link rel="ard" href="https://example.com/.well-known/ard.json"> <link rel="ai-catalog" href="https://example.com/.well-known/ai-catalog.json">
Serve the same document at /.well-known/ai-catalog.json too. That is the predecessor
path and crawlers written against the earlier draft still look there. It costs one route.
Try it on your own resource
Publishing takes one file. This checks whether it worked, across every public registry rather than only ours.
pip install ard-publish python -m ard_publish check yourdomain.com
Step 3, verify, because publishing is not indexing
This is the step everyone skips. A perfect manifest tells you nothing about whether any registry returns you, and registries choose their own crawl frontiers. One of them only crawls the top 100,000 domains, so a smaller publisher can be flawlessly conformant and indexed nowhere.
python -m ard_publish check example.com
That fetches your manifest, validates it, and asks every public registry whether they return your domain for your own representative queries. The web console does the same without installing anything.
The mistake that costs you everything
Leaving out representativeQueries.
It is the field registries build their semantic index from. Without it your entry is a valid catalogue entry that no search will ever return: the manifest validates, serves a 200, and is silently unfindable. The specification's own conformance tool flags its absence for exactly this reason.
Write two to five per entry, phrased as the request someone would actually make. Not "enterprise-grade geospatial platform" but "how far is it from Berlin to Prague".
Two smaller traps
- The wrong MCP media type. Three spellings are live across different indexes, and
registries that match exactly will drop you. Use
application/mcp-server-card+json, which is the one the conformance tool accepts. - A description written for a human browsing a pricing page. The description feeds the semantic index. Say what the thing does, plainly, in one sentence.
Use Neuronto from your agent
One call searches this index and every other public ARD registry. No key, no signup. Or install it as an MCP server and let the agent search from the interface it already speaks.
curl -s https://neuronto.com/search \
-H 'content-type: application/json' \
-d '{"query":{"text":"scrape a website"},"federation":"auto"}'
claude mcp add --transport http neuronto https://neuronto.com/mcp