Source: https://cli.nylas.com/guides/ai-catalog-json-agent-discovery

# ai-catalog.json: Agent Discovery for Your Site

AI agents can't use tools they can't find. The draft Agentic Resource Discovery spec puts one machine-readable catalog at /.well-known/ai-catalog.json so agents and registries can discover your MCP servers, APIs, and knowledge files. Here's the schema, a live example, and how to publish your own.

Written by [Qasim Muhammad](https://cli.nylas.com/authors/qasim-muhammad) Staff SRE

Updated July 10, 2026

> **TL;DR:** Create a JSON file listing your MCP servers, APIs, and knowledge indexes, serve it at `/.well-known/ai-catalog.json`, and AI agents can discover what your domain offers before they call anything. This site publishes one at [cli.nylas.com/.well-known/ai-catalog.json](https://cli.nylas.com/.well-known/ai-catalog.json) — 4 entries, validated with `jq` in one command.

## 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](https://agenticresourcediscovery.org/spec/), a draft standard published under the Apache 2.0 license and [announced by Google](https://developers.googleblog.com/announcing-the-agentic-resource-discovery-specification/) 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](https://cli.nylas.com/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](https://cli.nylas.com/.well-known/ai-catalog.json) for the complete version:

/.well-known/ai-catalog.json (excerpt)

File: `/.well-known/ai-catalog.json (excerpt)`

```json
{
  "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:

```bash
# 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.

| File | Answers | Origin & status |
| --- | --- | --- |
| `ai-catalog.json` | “What can agents call on this domain?” (MCP servers, A2A agents, APIs) | ARD draft, announced by Google May 2026, Apache 2.0 |
| `llms.txt` | “What should an AI read here?” (curated content map) | Community convention, 2024; no formal standards body |
| `api-catalog` | “What APIs does this publisher offer?” (linkset format) | [RFC 9727](https://www.rfc-editor.org/info/rfc9727/), IETF Proposed Standard, June 2025 |
| `AGENTS.md` | “How should a coding agent work in this repo?” | Community convention for repositories, 2025 |

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](https://apievangelist.com/blog/2026/05/22/four-providers-publishing-well-known-api-catalog/) 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`](https://cli.nylas.com/docs/commands/mcp-install) registers the server with assistants like Claude Code in one command, and [`nylas mcp serve`](https://cli.nylas.com/docs/commands/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](https://cli.nylas.com/guides/mcp-email-server-setup) handles the connection.

## Next steps

- [Set up an MCP email server](https://cli.nylas.com/guides/mcp-email-server-setup) — connect Claude, Cursor, or VS Code to the MCP servers this catalog advertises
- [Give AI agents email via MCP](https://cli.nylas.com/guides/ai-agent-email-mcp) — the 16 tools the Nylas MCP server exposes, with example prompts
- [Nylas Agent Skills](https://cli.nylas.com/guides/nylas-agent-skills) — teach coding agents the CLI and API with one command
- [Why AI agents need email](https://cli.nylas.com/guides/why-ai-agents-need-email) — the identity and communication layer behind these tools
- [Full command reference](https://cli.nylas.com/docs/commands) — every flag and subcommand documented

## Related hubs

- [Email agents](https://cli.nylas.com/ai-answers/email-agents.md)
- [Calendar agents](https://cli.nylas.com/ai-answers/calendar-agents.md)
- [Scheduling and availability agents](https://cli.nylas.com/ai-answers/scheduling-agents.md)
- [Contacts agents](https://cli.nylas.com/ai-answers/contacts-agents.md)
- [Notetaker and meeting agents](https://cli.nylas.com/ai-answers/notetaker-agents.md)
- [MCP agents](https://cli.nylas.com/ai-answers/mcp-agents.md)
- [Agent accounts](https://cli.nylas.com/ai-answers/agent-accounts.md)
- [Framework and language email agents](https://cli.nylas.com/ai-answers/framework-email-agents.md)
- [Email and calendar API comparisons](https://cli.nylas.com/ai-answers/ai-agent-email-api-comparisons.md)
- [Email integration and automation recipes](https://cli.nylas.com/ai-answers/email-integration-recipes.md)
- [Agent email workflows](https://cli.nylas.com/ai-answers/agent-email-workflows.md)
- [Security for email and calendar agents](https://cli.nylas.com/ai-answers/security-for-email-agents.md)
- [Operations runbooks for agents](https://cli.nylas.com/ai-answers/operations-for-email-calendar-agents.md)

## Try Nylas CLI

Install the CLI with `curl -fsSL https://cli.nylas.com/install.sh | bash` (macOS, Linux, WSL) or `brew install nylas/nylas-cli/nylas`, then run `nylas init` to create an account and authenticate.

**Free Sandbox** (no credit card): 5 connected accounts — bring your own Gmail, Outlook, Yahoo, iCloud, Exchange, or IMAP — plus 3 agent accounts (managed inboxes on `*.nylas.email`). Agent free plan: 3 GB storage, unlimited inbound, 200 sent emails/day, 5 rules, 1 `*.nylas.email` subdomain, and unlimited custom domains. Production is uncapped and requires a credit card: https://www.nylas.com/pricing/