For publishers
How to publish an ARD manifest
Serve a JSON manifest at /.well-known/ard.json on your domain listing what you offer, add an Agentmap: line to robots.txt and a <link rel="ard"> tag, and put 2 to 5 representative queries on every entry. Registries crawl it from there. There is no submission form and no allowlist.
Step 1: write the manifest
The whole document is a spec version, an optional host block, and an array of entries.
{
"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"
],
"tags": ["weather", "forecast"]
}
]
}
The identifier is a domain-anchored URN: urn:air:<your-domain>:<namespace>:<name>.
The publisher segment has to be a domain you control, because that is what publisher-authority
binding checks.
Step 2: get representativeQueries right
This is the field that decides whether you are findable, and it is the one most often left out.
Registries build their semantic index from it. An entry without representative queries is a valid catalogue entry that no search will ever return. The specification's own conformance tool flags its absence for exactly that reason.
Write 2 to 5, phrased the way someone asks for the thing, not the way you describe it:
| Weak | Strong |
|---|---|
| "weather data platform" | "will it rain in London tomorrow" |
| "enterprise document intelligence" | "read this PDF and pull out the invoice total" |
| "scalable web extraction" | "scrape a website that blocks bots" |
Step 3: advertise it on all four paths
# robots.txt Sitemap: https://example.com/sitemap.xml 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. It is the predecessor
name, and crawlers written against the earlier draft still look there.
Step 4: check that it worked
Publishing is not being indexed. Use the SDK, or run a free audit that fetches your manifest and asks every public registry whether they actually return you.
pip install ard-publish python -m ard_publish validate .well-known/ard.json python -m ard_publish check example.com
The mistakes that cost you silently
- No representativeQueries. Validates fine, never returned.
- The wrong MCP media type. Three spellings are live in the ecosystem. Registries that
match exactly will drop you. Use
application/mcp-server-card+json. - Only one discovery path. A crawler checking robots.txt will never see a manifest that exists only at the well-known path.
- A description written for humans browsing a marketing page rather than for a machine matching a task.
Check your own domain. The console fetches what you publish and asks every public registry whether they return you.
Run a free audit