AI Catalog

ia.ai-catalog · 4.21

Find MAY Recommendation AR-FIND-04 AgentReady requirement

Why it matters

An AI Catalog gives agents one machine-readable list of the AI resources of a site: MCP servers, APIs, skills and docs. Agents find it through links, so link it from the home page.

How to fix it

Publish a valid AI Catalog and advertise it from the homepage head and HTTP Link header.

Create /.well-known/ai-catalog.json with specVersion and entries. Give each entry an identifier, a media type and exactly one same-origin URL or inline data value.

{
  "specVersion": "1.0",
  "entries": [
    {
      "identifier": "urn:air:example:mcp",
      "type": "application/mcp-server-card+json",
      "url": "https://example.com/mcp/server-card"
    },
    {
      "identifier": "urn:air:example:openapi",
      "type": "application/openapi+json",
      "url": "https://example.com/openapi.json"
    }
  ]
}

Serve the file as application/json with HTTP 200.

Add a link rel="ai-catalog" in the homepage head and an equivalent HTTP Link header that points to the same catalog.

<link rel="ai-catalog" href="/.well-known/ai-catalog.json">

Link: </.well-known/ai-catalog.json>; rel="ai-catalog"

Verify

curl -sS -D - https://{domain}/

Expected: The homepage head and HTTP Link header advertise the same catalog. Fetch that URL and check specVersion and valid entries; a link from llms.txt alone does not satisfy both advertisements.

Run a new scan for this checkpoint:

isagentready results {domain} --checkpoint ia.ai-catalog

Details Mapping, lifecycle and references

AR mapping: Direct relation
Evidence source: agentready.org AR-FIND-04
Score role: Bonus
Introduced: 2026-08-24
Revised: 2026-10-30
Methodology version: 2026-10-30

Checkpoint data (JSON)