What is ai-catalog.json? Agent discovery for products

If your product exposes an MCP server, an A2A agent, an OpenAPI tool or an agent skill, an AI client still needs to answer a basic question before it can use any of them: where is the capability, and what exactly is it?

ai-catalog.json is an emerging answer to that discovery problem. It is a machine-readable catalog that a publisher can host on its own domain, normally at /.well-known/ai-catalog.json. The catalog lists AI artifacts and points to their native descriptions. A registry can crawl those catalogs, index them and return a suitable capability to an agent.

The important qualification is that this is not a new Google ranking file. The AI Catalog and the newer Agentic Resource Discovery (ARD) work describe how agents discover and verify capabilities; they do not promise that publishing a file will improve Google rankings, AI Overviews or brand citations. That distinction matters for both implementation and measurement.

The short answer: a directory for agent capabilities

The AI Catalog specification defines a typed, nestable JSON container. Each entry identifies an artifact by a type and either links to its native metadata with url or embeds the metadata with data. The catalog can describe different protocols without replacing them.

The AI Catalog documentation shows a minimal shape like this:

{
  "specVersion": "1.0",
  "host": {
    "displayName": "Example Tools"
  },
  "entries": [
    {
      "identifier": "urn:air:example.com:mcp:analytics",
      "displayName": "Analytics assistant",
      "type": "application/mcp-server-card+json",
      "url": "https://example.com/mcp/server-card.json",
      "description": "Reads approved analytics data for reporting tasks.",
      "tags": ["analytics", "reporting"]
    }
  ]
}

The claim is narrow: this file gives a compatible client a standard entry point to a list of capabilities. The AI Catalog specification defines the core schema, discovery location, conformance levels and optional trust manifest; it does not define how an MCP server or A2A agent itself works. Those protocol-specific documents remain the source of truth for invocation, authentication and behaviour.

Why this exists: installation does not scale

Today, many agent integrations are install-first. A developer copies a server URL into configuration, connects a plugin or hardcodes an agent card. That is workable for a few trusted tools. It becomes expensive when a team has hundreds of capabilities or when a user needs a capability that was not installed in advance.

The practical observation behind ARD is that discovery and execution are different jobs. A catalog helps an agent find a candidate. The native artifact description explains how to connect. The runtime protocol then performs the actual operation. Keeping those layers separate lets one catalog list MCP servers, A2A agents, OpenAPI tools, skills and nested catalogs without forcing them into one execution format.

This is also why a catalog is not the same thing as a product feed. A product feed describes items for shopping or inventory decisions. An AI catalog describes machine-usable capabilities and the metadata needed to resolve them. A SaaS product may publish both, but they solve different discovery problems.

AI Catalog, ARD and native cards: three layers

Layer	What it answers	Typical artifact
Native protocol metadata	How does this capability work?	MCP Server Card, A2A Agent Card, OpenAPI document or skill metadata
AI Catalog	What capabilities does this publisher expose?	/.well-known/ai-catalog.json
ARD registry	Which catalog entry matches this request?	A registry search endpoint such as POST /search

Google’s ARD announcement describes catalogs as publisher-hosted inventories and registries as search systems that crawl and index them. It also adds a trust layer so a client can verify the publisher before connecting. Hugging Face’s reference implementation makes the same separation concrete: its Discover service turns search results into catalog entries, while the returned resource still uses its native skill or MCP representation.

That architecture creates an evidence boundary. A catalog can say that an endpoint exists and identify its type. It cannot, by itself, prove that the endpoint is safe, available, accurate or appropriate for a sensitive task. Those claims require endpoint checks, authentication policy, provenance and, where relevant, signed trust metadata.

What should go in a catalog entry?

Start with the fields that make an entry unambiguous:

• a stable identifier owned by the publisher’s namespace;
• a human-readable displayName and concise description;
• the protocol-specific type;
• either a retrievable url or inline data, not both;
• tags or capability labels that describe what the resource can actually do;
• a canonical endpoint and documentation URL where the native protocol expects them.

The AI Catalog schema requires the core identity and type fields, and its examples use URN-like identifiers. The exact type string is important: application/mcp-server-card+json, application/a2a-agent-card+json and application/ai-catalog+json tell a consumer what it should fetch or parse. Do not put a marketing category in type and assume the client will infer the protocol.

Descriptions should be operational rather than promotional. “Helps teams work smarter” gives a registry little basis for matching. “Reads read-only Google Analytics 4 properties and returns a weekly acquisition summary” states the capability, the data boundary and a likely user intent. Keep the description aligned with the actual permissions and endpoint behaviour; stale metadata is a discovery bug, not just a copy issue.

A safe publishing workflow

1. Inventory real capabilities

List the endpoints, agents, skills and documents that are currently available. Record the owner, authentication method, supported operations, data sensitivity, lifecycle status and native metadata URL. Exclude experiments that cannot be reached or maintained.

The condition matters: a catalog is only useful when its entries describe live resources. A static list of retired endpoints can cause agents to select a capability that fails at runtime, while an overly broad list can expose an internal tool to consumers who were never meant to see it.

2. Generate the manifest from one source of truth

Keep capability metadata in the same registry or deployment configuration that owns the endpoint. Generate ai-catalog.json during a release, validate it against the current schema and publish it with the service. Do not ask a content editor to maintain a second hand-written inventory after every API change.

This is the same principle as a sitemap: it is a useful index, not the canonical business database. The endpoint’s native card or API description remains authoritative for invocation details; the catalog should link to it and provide enough context for discovery.

3. Serve it at a stable well-known URL

Publish the file at:

https://example.com/.well-known/ai-catalog.json

Return a successful response to an unauthenticated discovery request if the catalog is meant to be public. Set a JSON content type, use HTTPS, avoid accidental redirects to a login page and make sure the file is available from the canonical host. If the catalog is intentionally private, document the authenticated distribution path instead of pretending that a public registry can discover it.

4. Validate trust and permissions separately

Discovery is not authorization. Before a client connects, verify the publisher identity, endpoint origin, credentials, scopes, rate limits, data handling and version. For production or high-impact workflows, use the trust and provenance mechanisms supported by the selected ARD/AI Catalog implementation, and keep human approval in the loop for destructive or sensitive operations.

The ARD announcement describes cryptographic verification as a separate phase between discovery and runtime connection. That ordering is a useful implementation test: if your system invokes a newly discovered endpoint before verifying who published it and what it can access, the catalog has become an untrusted command channel.

5. Monitor freshness like an API contract

Test the well-known URL, schema validity, linked artifact availability and declared protocol types in CI. Alert when an entry points to a 404, when its native metadata changes incompatibly or when a capability is removed without a catalog update. Keep a changelog or version field where consumers need to distinguish a metadata refresh from a breaking endpoint change.

What ai-catalog.json does not do

It does not replace SEO

Google’s guidance for AI search says ordinary technical SEO, crawlability, indexability and useful content remain relevant. It does not say that ai-catalog.json is required for AI Overviews or that the file is a ranking signal. Use a catalog to expose agent capabilities; use HTML, structured data, sitemaps and clear content to make the public product understandable in search.

It does not replace Schema.org Product markup

Product structured data describes a real product, offer, availability and related commercial facts for search and other consumers. An AI catalog describes a capability endpoint. If a product has an agent-facing API, it may need both layers, but one should not be disguised as the other.

It does not make an ordinary website callable

A catalog entry that points to a marketing page is not automatically an agent tool. The destination must expose a documented, reachable interface and define authentication, inputs, outputs, errors and limits. For a brochure site with no agent capability, publishing an empty or invented catalog adds little value.

It does not guarantee discovery or use

A registry may not have crawled the catalog. A client may support only some artifact types. A matching capability may still lose to a more trusted, more relevant or better-maintained entry. Measure catalog availability, registry indexing, successful resolution and completed tasks separately; do not report publication alone as adoption.

A practical checklist for product teams

Before publishing, ask:

1. Does every entry point to a real, currently supported capability?
2. Is the identifier stable and unique under a domain the publisher controls?
3. Does type match the native protocol metadata format?
4. Can an unauthenticated client retrieve the public catalog over HTTPS?
5. Are permissions, data boundaries and destructive actions documented elsewhere?
6. Is the catalog generated, schema-validated and tested in deployment?
7. Are trust verification and authorization enforced before invocation?
8. Do monitoring and removal procedures keep the manifest fresh?

If several answers are no, adding the file is premature. Fix the capability contract first, then expose the smallest catalog that a client can safely understand.

Resources

1. AI Catalog specification — normative schema, discovery, conformance and trust-manifest overview.
2. AI Catalog documentation and examples — working-group repository and implementation guidance.
3. Google Developers Blog: Announcing the Agentic Resource Discovery specification — catalogs, registries, verification and runtime discovery.
4. Hugging Face: Agentic Resource Discovery — reference implementation details for static catalogs and registry search.
5. Google Search Central: AI Features and Your Website — why normal SEO remains the baseline for Google AI search features.

For a SaaS team deciding whether to expose its first agent capability, the practical sequence is: publish one accurate entry, link to the native protocol document, verify trust before execution and keep the manifest current as the endpoint changes. The technical SEO service can review the separate search surface, while the Evidence Loop method provides a way to test the agent task and its failure conditions. This keeps catalog availability, agent completion and search visibility as three measurable outcomes instead of one blended promise.