ai-catalog.json is a small JSON file you publish at /.well-known/ai-catalog.json that tells AI agents what your site can do — not what it says, but what it offers: APIs, MCP servers, A2A agents, skills. It is the center of Agentic Resource Discovery (ARD), an open specification announced by Google and a Linux Foundation working group in late May 2026. Think of it as sitemap.xml for the agent era: sitemaps declare your pages to search crawlers; ai-catalog.json declares your capabilities to agent registries. Here is what it is, what goes in it, and whether you should publish one today.
What problem does ai-catalog.json solve?
Right now, when an AI agent needs a capability — "find me a tool that sends transactional email" or "which API can transcribe this audio" — it has no reliable way to discover one. Most "AI integrations" today are just catalog text dumped into embeddings once and called done. That breaks the moment inventory changes or prices update: stale data by design.
ARD splits the problem into two halves. The first half is the file: every site publishes a static JSON document describing its agent-facing resources. The second half is the registry: crawlers (ARD registries) fetch those files, index the entries, and expose a search API so agents can find capabilities by natural-language need. An agent queries the registry, gets a semantic match, and can inspect or invoke the tool at runtime — no pre-installation required.
The sitemap analogy is deliberate and exact:
- sitemap.xml declares your pages; ai-catalog.json declares your capabilities.
- Search engine crawlers read sitemaps; ARD registry crawlers read catalogs.
- Both live at well-known paths, both are declarative, both are crawled automatically once discoverable.
Who is behind the ARD spec?
The spec is Apache 2.0 licensed and was at v0.9 draft when announced. The named co-authors are Junjie Bu (Google), R.V. Guha (Microsoft), and Shaun Smith (Hugging Face), with acknowledgements spanning AWS, Cisco, GitHub, Salesforce, Snowflake, and Nvidia — broad industry backing from day one. That backing matters: a discovery standard only works if the discoverers and the publishers agree on the format, and ARD launched with both sides at the table.
Be clear-eyed about the timeline, though. An independent census in June 2026 probed 39 leading domains — including the working-group members themselves — and found zero discoverable catalogs and no public ARD registry an agent could actually query. The spec is real and well-designed; as a working channel it is a forecast, not a finding. We will return to what that means for your decision below.
What goes inside ai-catalog.json?
The file has three parts: a specVersion, a host block describing your domain, and an entries array. Each entry describes one capability and carries:
- identifier — a domain-anchored URN that uniquely names the resource.
- displayName — a human-readable name.
- type — an IANA media type naming the kind of resource (e.g. an MCP server card or agent card type).
- url or data — either a URL pointing at the resource or the resource description inline.
- representativeQueries (optional) — example natural-language queries the entry should match. This is arguably the most important optional field: it is how you teach the registry's semantic matching what your tool is for.
- tags (optional) — topical labels for filtering.
- trustManifest (optional) — trust and provenance information.
A minimal entry for a hypothetical SEO audit API might look like this:
{
"specVersion": "0.9",
"host": {
"name": "Example Tools",
"url": "https://example.com"
},
"entries": [
{
"identifier": "urn:example.com:seo-audit-api",
"displayName": "SEO Audit API",
"type": "application/json",
"url": "https://example.com/api/audit",
"representativeQueries": [
"audit a website for technical SEO issues",
"check a page for missing meta tags"
],
"tags": ["seo", "audit", "api"]
}
]
}The whole file takes about an hour to write by hand for a small site. That low cost is the point: discovery infrastructure has to be cheap enough that publishing it needs no ROI justification.
Where do you host it?
At https://yourdomain.com/.well-known/ai-catalog.json, served as JSON with HTTP 200. The .well-known path is the standard location for machine-readable site metadata (the same directory that hosts security.txt and change-password), so registries know exactly where to look without configuration.
ARD also defines additional advertisement mechanisms — registries are expected to check several ways a site can point at its catalog — but the well-known path is the one to get right first. Validate that the file parses as JSON (a trailing comma will silently break consumers) and that it is reachable without JavaScript, since registry crawlers fetch it as a static document. Keep the file under a few hundred kilobytes; registries are designed for quick declarative reads, not bulk data transfer.
How ai-catalog.json fits the AI-discovery stack
ai-catalog.json is one file in a growing stack of AI-facing declarations, and each solves a different problem:
- robots.txt — controls which crawlers may access your site. Access control.
- llms.txt — guides language models to your most important content in clean Markdown. Content understanding. Generate one with the free llms.txt generator.
- ai.txt — declares your content's origin and AI-training policies. Provenance and policy. Build one with the ai.txt generator.
- ai-catalog.json — declares your callable capabilities to agent registries. Capability discovery.
- agents.md — an emerging markdown manifest describing how agents should interact with your site. Interaction guidance.
These are complementary, not competing. A site serious about the agent era will eventually publish all of them: robots.txt for access, llms.txt for understanding, ai.txt for policy, ai-catalog.json for capabilities, agents.md for behavior. If you are starting from zero, llms.txt is the highest-leverage first file, because today's models and answer engines can use it immediately.
Should you publish an ai-catalog.json today?
It depends on what you ship:
Yes, publish one if:
- You run an MCP server — the Model Context Protocol's server descriptors are exactly the kind of capability ARD registries will index.
- You operate an A2A agent or any agent with a public agent card.
- You maintain a public skills repository or a callable API that third-party agents could use.
- You want to be genuinely early. Publishing costs an hour; if registries arrive, you are already indexed.
Wait if:
- You have no agentic resource to advertise. A catalog with no entries is worse than no catalog — it is a promise of capabilities you do not have.
- You expect traffic from it this quarter. There is no public agent-queried registry today, so treat the file as a low-cost bet on the future, not a program with measurable returns.
The honest framing: ai-catalog.json is infrastructure for a world that is still arriving. Publish it if you have something to declare; skip the theater if you do not.
How an ARD registry would use your catalog: the search flow
To make the abstract concrete, here is the sequence ARD is designed for. A user asks their AI assistant: "find me an API that audits a website for SEO issues." The assistant does not search the web for blog posts about SEO APIs. Instead it queries an ARD registry with that natural-language need. The registry compares the query against the representativeQueries fields, displayName values, and tags across every catalog it has crawled, ranks the matches, and returns your entry — including the url where your API lives and the type telling the agent how to invoke it.
The agent then fetches your resource description, checks the trustManifest for provenance, and calls your API at runtime. No SDK was installed. No integration was pre-built. Discovery happened through structured data, and invocation happened through your published interface. This is the "structured data + real-time function calls" model that replaces today's stale embedding dumps — and it only works if publishers describe their capabilities in a format registries can crawl. That format is ai-catalog.json.
Notice what this flow does not require: the agent never needed to read your marketing pages, parse your pricing HTML, or guess from your homepage copy. Every one of those is a failure point in today's agent integrations. The catalog removes the guessing.
What to watch next
Three signals will tell you ARD has crossed from forecast to finding: a major model provider announcing it queries an ARD registry, working-group members publishing their own catalogs (the June 2026 census found none — watch for the first), and the appearance of the Agentmap robots.txt directive or link rel="ai-catalog" discovery tags in the wild. Until then, keep the file small, keep it valid, and keep your llms.txt excellent — because llms.txt is the discovery file that works today. For the broader picture of the agentic discovery stack, the ARD complete guide and the ai-catalog.json explainer are the deepest independent write-ups available.
FAQ
Is ai-catalog.json an official standard?
It is an open specification (Apache 2.0, v0.9 draft) developed by Google with a Linux Foundation working group, co-authored by engineers from Google, Microsoft, and Hugging Face. It is a draft spec with industry backing, not yet a finalized or universally adopted standard.
Does publishing ai-catalog.json help my SEO?
Not directly. It is not read by Googlebot or Bingbot, and it carries no ranking signal. Its purpose is discovery by AI agents through ARD registries — a different channel from search.
What is the difference between ai-catalog.json and llms.txt?
llms.txt describes your content so language models can understand and cite it. ai-catalog.json describes your capabilities (APIs, MCP servers, agents) so AI agents can discover and invoke them. A content site needs the first; a tool or API provider eventually needs both.
Do I need ai-catalog.json if I already have an MCP server?
You do not need it for the MCP server to function — MCP clients connect directly. The catalog is about discovery: helping agents that do not know you exist find your server through a registry. If discoverability matters to your API business, it is worth the hour.
Where exactly do I put the file?
At /.well-known/ai-catalog.json on your domain, served as JSON over HTTPS with a 200 status. Validate the JSON syntax before publishing — one malformed file can cause a registry to skip your entire domain.
Is anyone actually using ARD registries yet?
As of mid-2026, no public registry that agents query has been documented, and a census of 39 major domains found zero published catalogs. Treat ARD as emerging infrastructure: real spec, real backing, real future — but not a live channel yet.
