AI Catalog explained: one file that lists a site's agents

An AI Catalog is a JSON document a host publishes to list its AI artifacts: A2A agents, MCP servers, skills, other catalogs, and anything else with a media type. Each entry names what kind of artifact it is and links to it, or carries it inline. A client that reads one file learns everything the host offers, across protocols.

The format comes from the Agent Card Working Group. Its specification is a draft, last revised on October 1, 2026, and it says the document may change at any time. This guide covers what a catalog contains, how clients find it, where adoption stands, and how to publish one.

Why a catalog

A2A 1.0 gives each domain one well-known location for an Agent Card, /.well-known/agent-card.json. That works for a company with one agent. It doesn’t work for a company with a quoting agent and a tracking agent, or for a platform that hosts agents for hundreds of businesses on one domain. The open A2A pull request that proposes the catalog gives exactly this reason: one card per domain breaks multi-agent and multi-tenant deployments.

A catalog removes the limit. It can list any number of artifacts, it isn’t tied to one protocol, and it can point to other catalogs so a large host can split its list.

What’s in one

The top level is small.

Member	Required	What it holds
specVersion	Yes	The specification version, as "Major.Minor", such as "1.0"
entries	Yes	The list of artifacts; it may be empty
host	No	Who operates the catalog: displayName (required inside host), plus optional identifier, documentationUrl and logoUrl
extensions	No	Custom data

Each entry describes one artifact.

Member	Required	What it holds
identifier	Yes	A string that names the artifact; unique in the catalog, together with version when several versions are listed
type	Yes	What the artifact is, as a media type
url or data	Exactly one	Where to fetch the artifact, or the artifact itself inline
displayName, description	No	A name and blurb; leave them out when the artifact carries its own
version	No	The artifact’s version; required when one identifier is listed more than once
tags	No	Keywords for filtering
updatedAt	No	When the entry last changed, as an RFC 3339 timestamp
publisher	No	Who publishes the artifact: identifier and displayName
trustManifest	No	Signed identity and provenance claims (Level 3)

For an A2A agent, the specification asks the catalog not to repeat the card’s name, description or version. The card is the authoritative copy, and two copies drift apart.

Identifiers. Any string works, but the specification recommends a globally unique URI and offers a format: urn:air:{publisher domain}:{namespace}:{name}, such as urn:air:example.com:a2a:quotes. The domain in the identifier is a label, not proof. Nothing in the syntax shows that example.com published the entry.

Types. The specification lists types it expects to see often:

Type	Artifact
application/a2a-agent-card+json	An A2A Agent Card
application/mcp-server-card+json	An MCP Server Card
application/ai-catalog+json	Another AI Catalog (nested)
application/agent-skills+json, +md, +zip, +gzip	Agent Skills, as metadata, Markdown or a bundle
application/agent-plugins+zip, +gzip	An agent plugin bundle

Any other string is allowed; how a client handles a type it doesn’t know is up to the client.

An example

Illustrative: a freight company with two agents and an MCP server.

{
  "specVersion": "1.0",
  "host": {
    "displayName": "Example Freight",
    "identifier": "example.com",
    "documentationUrl": "https://example.com/developers"
  },
  "entries": [
    {
      "identifier": "urn:air:example.com:a2a:quotes",
      "type": "application/a2a-agent-card+json",
      "url": "https://example.com/.well-known/agent-card.json"
    },
    {
      "identifier": "urn:air:example.com:a2a:tracking",
      "type": "application/a2a-agent-card+json",
      "url": "https://example.com/agents/tracking/agent-card.json"
    },
    {
      "identifier": "urn:air:example.com:mcp:rates",
      "type": "application/mcp-server-card+json",
      "url": "https://example.com/mcp/server-card.json"
    }
  ]
}

The quoting agent’s card stays at the well-known path, so A2A 1.0 clients still find it. The tracking agent, which had no place before, now has one.

Conformance levels

The specification defines three levels. Each includes the one before.

Level	Name	Adds
1	Minimal	specVersion and entries, and every entry has an identifier, a type and exactly one of url or data
2	Discoverable	A host object naming the catalog’s operator; may be served at the well-known URI
3	Trusted	A signed Trust Manifest on each entry that clients should rely on, bound to the artifact and issued under a did:web identity for the publisher’s domain

A catalog at any level conforms. Clients may ignore the fields of levels they don’t support.

How clients find a catalog

A catalog can live at any URL. Its media type, application/ai-catalog+json, and its specVersion identify it, not its path. Three conventions help clients find one:

1. The well-known URI. A host may serve its catalog at /.well-known/ai-catalog.json. Clients doing domain-level discovery should try that path.
2. A Link header. Any response can point to the catalog with rel="ai-catalog" (RFC 8288).
3. An HTML <link> element. A page’s head can carry <link rel="ai-catalog" href="..." type="application/ai-catalog+json">.

For agents browsing a site, the specification suggests this order: the Link header first, then the HTML element, then the well-known URI as a fallback. A response with a JSON media type and a valid specVersion counts as the site’s catalog, even when it isn’t served as application/ai-catalog+json.

Where adoption stands

As of October 2, 2026, nothing is settled.

Proposal	Where	Status
Make the AI Catalog A2A’s preferred discovery path, keeping agent-card.json with its limits documented	A2A pull request 2240	Open since September 16, one approval
Add /.well-known/agent-card-list.json, a plain array of Agent Cards	A2A issue 2276	Open since October 1; its author has offered to converge on pull request 2240
Use /.well-known/ai-catalog.json to discover MCP servers over HTTP	MCP SEP-2127, MCP Server Cards	Open, in review
Agentic Resource Discovery (ARD), which describes the AI Catalog as its predecessor and uses /.well-known/ard.json	ARD v0.91	Proposal of August 26; its clients may also read ai-catalog.json

So there are at least two candidate files for the same list, and A2A hasn’t picked one. Publishing an AI Catalog is cheap, and both the A2A and MCP proposals name it. Keep agent-card.json in any case, because it is the only path A2A 1.0 defines.

Trust and security

A catalog is a claim by whoever controls the file, like an Agent Card. HTTPS shows it came from the domain. It doesn’t show that the entries are honest, and the specification describes the risks plainly:

• Poisoning. Someone who takes over the hosting account or the DNS can change URLs or add entries. Signed Trust Manifests (Level 3) bind each entry to the artifact and to a key the publisher’s domain authorizes, so a changed entry no longer verifies.
• Lookalike identifiers. urn:air:examp1e.com:... reads like urn:air:example.com:.... Treat identifiers as labels until a signature backs them.
• Nested catalogs. A catalog can point to one that points back. Clients should stop at four levels, as the specification recommends, and refuse a catalog URL they already visited on the same path.
• Entries on other domains. An entry may point to an artifact anywhere. Check that artifact on its own terms, not because the catalog lists it.

Publish yours

1. Keep your Agent Card at /.well-known/agent-card.json.
2. Write the catalog. The Agent Card generator has an AI Catalog tab that lists the card you build there, at Level 2.
3. Serve it at /.well-known/ai-catalog.json as application/ai-catalog+json. Caching headers, such as Cache-Control with a max-age and an ETag, let clients avoid refetching it.
4. Optionally, link it from your pages with <link rel="ai-catalog">.
5. Check it with the Agent Card validator: enter your /.well-known/ai-catalog.json URL or paste the catalog. It reports the catalog against the specification: required fields as failures, recommendations as warnings, and the level it reaches. The agent readiness scanner reports the same checks as part of a whole-site scan.
6. Update it when you add or retire an agent. Change an entry’s updatedAt when you change the entry.

How Emissar uses it

Emissar publishes its own catalog at /.well-known/ai-catalog.json, at Level 2, listing its A2A agent. Every business behind Front Door gets one too, listing its agent. The readiness scanner reports any site’s catalog without scoring it. Since October 2, 2026, EmissarBot also requests /.well-known/ai-catalog.json on each site it crawls (what it requests), so later adoption reports can count catalogs as well as Agent Cards. The first full count comes from the next monthly crawl.