Skip to content
SeenLens

ard.json and ai-catalog.json errors: how to fix your agent catalog

An agent catalog is a JSON file that lists agent resources, such as MCP servers and A2A agents, so agents can discover them. It lives at /.well-known/ard.json, or at the older ai-catalog.json. SeenLens reports an error when the file exists but is wrong, or when a catch-all page answers the path with HTML. If you have nothing to list, return a real 404 and the check does not apply.

By SeenLens · Last updated

Run the free 43-check scan on your page

What does the agent catalog check test?

Since rules 0.3.2 (2026-11-06), SeenLens first requests /.well-known/ard.json, the location Lighthouse 13.6 and ARD v0.91 use. If that file answers 200, SeenLens checks it with the rules below and ignores the specVersion value, as Lighthouse does. If it does not exist, SeenLens falls back to the older places Lighthouse 13.5 used: an Agentmap: line in robots.txt, a link element with rel="ai-catalog", a Link response header, and /.well-known/ai-catalog.json. SeenLens does not yet read rel="ard" link elements or headers.

Agent catalog check results
What SeenLens findsResult
No signal and the path answers 404 or another non-200 statusNot applicable. Nothing to fix.
No signal, but the path answers 200 with an HTML pageFail. A catch-all route is faking a file.
A signal, but the catalog does not loadFail
The file does not parse as JSON, or the content type is not JSONFail
The file has errors in entriesWarn, titled 'has errors'
The only gaps are missing displayName or representativeQueriesWarn, titled 'has gaps', low priority
The file passes every rulePass

SeenLens applies these rules to the file. The root must be a JSON object with specVersion and an entries array. A top level collections member is an error. Each entry needs:

  • identifier in the form urn:air:<publisher>[:<namespace>]:<name>.
  • displayName.
  • type, an agent resource media type such as application/mcp-server-card+json. A type SeenLens does not know gives a warning.
  • Exactly one of url or data.
  • representativeQueries with 2 to 5 sample queries. A missing list or another count gives a warning.
  • If present, trustManifest must be an object with an identity.

What is the current status of the spec?

The Agentic Resource Discovery (ARD) specification is a proposal. Version 0.91 is dated 2026-08-26 and its status is Proposal. The ARD project lists participants from Microsoft, Google, Hugging Face, GoDaddy and others, and licenses the work under Apache 2.0.

The location moved. Version 0.91 names /.well-known/ard.json as the well known URI and <link rel="ard"> as the HTML link. It calls /.well-known/ai-catalog.json and rel="ai-catalog" the predecessor, which consumers may also check. In the spec, entries is the only required top level member, and other top level members are ignored.

Lighthouse followed. Its current ard-schema audit (Lighthouse 13.6.0, the latest npm release on 2026-11-06) reads /.well-known/ard.json and rel="ard". It flags a manifest found only at the legacy location. The audit is not applicable when the site gives no signal and the path answers with a 4xx status.

SeenLens follows the new location since rules 0.3.2: it checks /.well-known/ard.json first and the legacy ai-catalog.json only when ard.json is missing. To work with older and newer consumers, serve the same file at both paths and keep specVersion in it. Current Lighthouse ignores extra top level members.

How can I check my catalog?

Terminal
curl -sI https://example.com/.well-known/ai-catalog.json
curl -s https://example.com/.well-known/ai-catalog.json | python3 -m json.tool | head -30

Look at the status and the content type. A text/html type with status 200 means a catch-all page answers the path. Then check that the JSON parses.

How do I fix it?

If you have no agent resources to list, delete the file and make sure the path returns a real 404. See soft 404 pages for catch-all routes. If you do run an MCP server or an agent, publish a valid catalog. This is a minimal file with one MCP server entry. Replace example.com with the domain you own.

/.well-known/ai-catalog.json
{
  "specVersion": "1.0",
  "entries": [
    {
      "identifier": "urn:air:example.com:server:search",
      "displayName": "Example search tool",
      "type": "application/mcp-server-card+json",
      "url": "https://example.com/mcp/server-card.json",
      "representativeQueries": [
        "find articles about invoice templates",
        "search the Example help center"
      ]
    }
  ]
}

The ARD spec requires the publisher part of identifier to be a fully qualified domain name. If you include a trustManifest, its identity must match that publisher domain.

Next.js and static sites

Place the file in public/.well-known/ai-catalog.json. Next.js serves static files from public with a type taken from the extension, which gives application/json. Copy it to ard.json in the same folder.

Nginx

nginx.conf
location = /.well-known/ai-catalog.json {
    default_type application/json;
    add_header Cache-Control "public, max-age=3600";
}

WordPress

Create a .well-known folder in the site root and upload the file with SFTP. Check that your host and any security plugin do not block dot folders. Then request the URL and check the content type.

Shopify

The Shopify theme template documentation lists special templates for robots.txt, llms.txt, llms-full.txt and agents.md. It does not list one for /.well-known paths. A Shopify store without a proxy in front of it should return the default 404 and skip this check.

How do I verify the fix?

  1. Run the curl commands. The status must be 200, the content type must contain json and the JSON must print.
  2. Scan the page with SeenLens. The check must pass, or show 'not applicable' if you removed the file.
  3. Run Lighthouse with the Agentic Browsing category and read the ARD audit. See Lighthouse agentic audit failures.

When can I ignore this check?

Publish a catalog only if you run something agents can use, such as an MCP server or an A2A agent. A normal content site has nothing to list. A real 404 is the correct answer. SeenLens then marks the check not applicable. A fake or empty file is worse than none, because Lighthouse counts it as a failed audit.

Scan your page with SeenLens

Sources