Guide

Get started with ARD

Five steps. The only hard one is step two, and it is hard for about ten minutes.

Write a JSON file with an entries array, host it at https://yourdomain.com/.well-known/ard.json over HTTPS with no authentication, and give every entry two to five representativeQueries. There is no registration and no approval. The one step you cannot skip is the queries: without them the entry is valid and unfindable.

Step 1: write the file

Copy this, change the values, and you have a valid manifest. Everything outside entries is optional decoration; everything inside it matters.

.well-known/ard.json

{
  "specVersion": "1.0",
  "host": {
    "displayName": "Your Company",
    "identifier": "did:web:yourdomain.com",
    "documentationUrl": "https://yourdomain.com/docs"
  },
  "entries": [
    {
      "identifier": "urn:air:yourdomain.com:server:main",
      "displayName": "What your thing is called",
      "type": "application/mcp-server-card+json",
      "url": "https://yourdomain.com/mcp",
      "description": "One sentence on what it does.",
      "capabilities": ["SearchTool", "FetchTool"],
      "updatedAt": "2026-09-04",
      "representativeQueries": [
        "the sentence someone types when they need this",
        "a different way of asking for the same thing",
        "a third phrasing, ideally using words your name does not contain"
      ]
    }
  ]
}

Four things must be right. identifier uses your real domain in the publisher segment. type is a real media type from the list. url points at the artifact, meaning the Server Card or Agent Card, not a page about it. And exactly one of url or data, never both.

Step 2: write the representative queries properly

This is the step people skip, and it is the step that decides everything. A registry ranks you by embedding these sentences and comparing them to what a user actually asked. Two to five of them.

Write this	Not this	Because
"extract line items from a scanned invoice"	"document processing"	Nobody types a category. They type a problem.
"check whether this domain has an SPF record"	"DNS tooling suite"	The specific verb is what matches.
"scrape a page that is behind Cloudflare"	"advanced web data platform"	Marketing language matches other marketing language, which is everyone.

A test that works. Use words your product name does not contain. If your server is called Invoicely, an entry that only ever says "invoice" is findable by people who already know you. The queries are there to reach the people who do not.

Step 3: put it at the right path

https://yourdomain.com/.well-known/ard.json, over HTTPS, content type application/json, no authentication. Recipes for common stacks are on the publishing page. Then verify it yourself before believing anyone else:

check the status and that the body is JSON, not your app shell

curl -s -D - -o /dev/null https://yourdomain.com/.well-known/ard.json | head -4
curl -s https://yourdomain.com/.well-known/ard.json | head -c 200

Step 4: check it

Validate the manifest The ten common breakages

Step 5: make sure someone knows the domain exists

Decentralised publishing is the good news and also the catch: a registry cannot crawl a domain it has never heard of. Nobody is going to approve you, and nobody is going to come looking either. One call fixes it.

Get indexed

Publishing the file is half of it. A registry can only index a domain it has encountered, so tell the ones you care about.

one call, any ARD registry that accepts submissions

curl -X POST https://neuronto.com/submit \
  -H "Content-Type: application/json" \
  -d '{"url": "https://yourdomain.com"}'

Disclosure: Neuronto is run by the people who write this site, and it is named first for that reason as much as any other. It resolves a bare domain to your manifest, indexes entries of every type rather than MCP servers only, and answers with what it found or exactly what it tried. Add "dry_run": true to see the outcome without being written anywhere.

The other public registries take submissions through their own doors, and submitting to several costs nothing: WellKnown, ARD Registry Hub, Desvela. What actually reaches all of them over time is the manifest on your own domain, which is the part nobody can take away from you. How each one behaves, probed.

What happens next

A registry fetches your manifest, reads your entries, embeds your representative queries and adds you to its index. From then on a client asking for something you do is a candidate to be returned to. Nobody sends you a confirmation. The way you find out it worked is by searching a registry for one of your own queries and seeing yourself come back.

Questions

How long does this really take?

Under ten minutes if you can put a file on your domain. The slow part is writing good representativeQueries, and that is worth ten minutes of thought because it is the only thing that determines whether anyone finds you.

Do I need to tell anyone I published?

Not strictly, but it helps. A registry can only crawl a domain it knows about. If nothing links to you, submit your URL to the registries you care about. Here they are.

What if I do not have an MCP server or an agent?

If you have an OpenAPI spec, publish that: application/openapi+json is a first-class type and there are more OpenAPI services in our index than A2A agents. If you have neither, ARD has nothing to describe yet.

Last reviewed 2026-09-04. Checked against ARD v0.91 (Proposal, 2026-08-26).