ai-catalog.json: Agent Discovery for Your Site

What is ai-catalog.json?

ai-catalog.json is a machine-readable manifest, served at /.well-known/ai-catalog.json, that tells AI agents which agentic resources a domain offers: MCP servers, A2A agents, APIs, and knowledge files. It's the core artifact of the Agentic Resource Discovery (ARD) specification, a draft standard published under the Apache 2.0 license and announced by Google in late May 2026 with backing from companies including Microsoft, GitHub, and Hugging Face.

The problem it solves is pre-invocation discovery. Protocols like MCP define how an agent calls a tool once it knows the endpoint, but nothing standard tells the agent the endpoint exists. Today that knowledge lives in hand-maintained config files and registries an agent may never see. ARD moves it to a predictable URL on the publisher's own domain, the same pattern that made robots.txt and sitemap.xml work for search crawlers.

The spec defines two primitives: the static catalog file on your domain, and registry services that crawl published catalogs and answer natural-language discovery queries. Adoption is early — the spec is weeks old as of July 2026 — which is exactly why publishing now costs one static file and positions your resources for every registry that starts crawling.

What goes in the file?

A catalog has three required parts: a specVersion string, a host object naming the publisher (displayName and domain identifier), and an entries array with one object per resource. Each entry carries 5 required fields: identifier (a URN like urn:ai:acme.com:tool:ocr), displayName, type, url, and description.

This site publishes a live 4-entry catalog listing the two hosted Nylas MCP servers (US and EU data regions), the llms.txt knowledge index, and the v3 API reference. Here is an abridged excerpt showing 2 of the 4 entries with shortened descriptions — fetch the full file for the complete version:

{
  "specVersion": "1.0",
  "host": {
    "displayName": "Nylas CLI",
    "identifier": "cli.nylas.com"
  },
  "entries": [
    {
      "identifier": "urn:ai:nylas.com:mcp:us",
      "displayName": "Nylas MCP Server (US)",
      "type": "application/mcp-server+json",
      "url": "https://mcp.us.nylas.com",
      "description": "Hosted Model Context Protocol server exposing Nylas email, calendar, and contacts tools to AI agents. Requires a Nylas API key; US data region."
    },
    {
      "identifier": "urn:ai:cli.nylas.com:knowledge:llms-txt",
      "displayName": "Nylas CLI knowledge index (llms.txt)",
      "type": "text/plain",
      "url": "https://cli.nylas.com/llms.txt",
      "description": "Curated index of guides, command reference, and AI answer hubs for the Nylas CLI, formatted for AI agents."
    }
  ]
}

The type field uses media-type strings; the spec's own example uses application/mcp-server+json for an MCP server entry. An optional trustManifest field carries security and compliance metadata, and a collections element can link out to sub-catalogs. Both are omitted here — a minimal, accurate catalog beats a speculative one while the spec is a draft.

How do I publish an ai-catalog.json for my site?

Publishing takes three steps and no new infrastructure: write the JSON, serve it at the well-known path, and validate it. On a static or Next.js site that means dropping one file in your public directory — this site's catalog is a 40-line static file, deployed like any other asset.

1. Inventory your agentic resources. List only what actually exists: a hosted MCP server, a public API reference, an llms.txt. Don't invent placeholder entries — registries will fetch every URL you list.
2. Write the catalog with specVersion, host, and one entry per resource, then serve it at /.well-known/ai-catalog.json over HTTPS.
3. Validate it. The file is plain JSON, so jq catches syntax errors and asserts all 5 required fields on every entry in one pass.

The check below fetches a live catalog and prints each entry's name and endpoint. Run it against your own domain after deploying; a parse error or empty output means the file is malformed or missing:

# Fetch and validate a live catalog
curl -s https://cli.nylas.com/.well-known/ai-catalog.json | jq '
  {spec: .specVersion, host: .host.identifier,
   resources: [.entries[] | "\(.displayName) -> \(.url)"]}'

# Assert the required fields exist on every entry
curl -s https://cli.nylas.com/.well-known/ai-catalog.json | jq -e '
  .entries | all(has("identifier") and has("displayName")
                 and has("type") and has("url") and has("description"))'

How does it compare to llms.txt, api-catalog, and AGENTS.md?

Four discovery files now target machine readers, and they answer different questions. llms.txt curates content for AI readers; RFC 9727's api-catalog lists APIs; AGENTS.md instructs coding agents inside a repository; ai-catalog.json indexes callable agentic resources. A site with all four is describing itself to four different consumers.

The adoption numbers show how early this space is. RFC 9727 reached Proposed Standard in June 2025 after 13 draft revisions, yet an API Evangelist survey in May 2026 found only four API providers publishing a real /.well-known/api-catalog. Publishing any of these files today puts you in a group small enough to count by hand.

What will AI agents do with the catalog?

Agents and registries use the catalog for tool selection before invocation. Instead of packing every candidate tool into the model's context window, an agent queries a registry that has crawled published catalogs, gets ranked matches, and then connects to the winner over its native protocol — MCP for the entries above. Discovery happens in a search service; the context window only sees the tools that made the cut.

For the Nylas entries specifically, an agent that discovers the MCP servers still needs credentials — both endpoints return HTTP 401 without a Nylas API key. A human (or the agent's operator) connects with the CLI: nylas mcp install registers the server with assistants like Claude Code in one command, and nylas mcp serve runs a local proxy to the same 16 hosted email, calendar, and contacts tools. The catalog handles being found; the MCP setup guide handles the connection.

Next steps

• Set up an MCP email server — connect Claude, Cursor, or VS Code to the MCP servers this catalog advertises
• Give AI agents email via MCP — the 16 tools the Nylas MCP server exposes, with example prompts
• Nylas Agent Skills — teach coding agents the CLI and API with one command
• Why AI agents need email — the identity and communication layer behind these tools
• Full command reference — every flag and subcommand documented