How to Implement ai-catalog.json on your SaaS Domain

Introduction to Agentic Resource Discovery

The Agentic Resource Discovery (ARD) protocol allows automated agents (such as Claude Code, Cursor, and GitHub Copilot's Agent Finder) to dynamically discover your APIs at runtime. Instead of registering your API key on multiple external directories, you simply drop a static "ai-catalog.json" file at a well-known path on your domain. Registries crawl your domain, index your tools, and make them available to agents.

Step 1: Hosting the Manifest File

Your manifest must be served at a specific path under your root domain. Independent registry crawlers look for this path first:

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

Step 2: Configuring Essential CORS Headers

Because autonomous agents (like GitHub Copilot) query this file directly from their browser or terminal clients, your web server MUST serve the catalog with open Cross-Origin Resource Sharing (CORS) headers. If CORS headers are not set to allow wildcard origins, registries or client agents will fail to fetch your file.

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Content-Type: application/json

Step 3: Setup DNS Fallback (Optional but Recommended)

In case your website runs on a single-page app framework that redirects unknown well-known paths, registries will fall back to DNS lookup. You can advertise your catalog URL by publishing a TXT record at the subdomain _catalog._agents:

_catalog._agents.yourdomain.com. IN TXT "url=https://cdn.yourdomain.com/assets/ai-catalog.json"

Step 4: Establish Domain Identity using did:web

Trust is the foundation of execution. To prove that the catalog truly belongs to your organization, the manifest uses did:web (a Decentralized Identifier method). By hosting a did.json file at https://yourdomain.com/.well-known/did.json, you bind your domain identity cryptographically. This allows registries to verify signatures on your capability catalog.

Generate your Catalog Manifest

Use the schema playground below to draft and copy your spec-compliant catalog manifest file. Place it on your server and submit your domain to get indexed!

{
  "specVersion": "1.0",
  "host": {
    "displayName": "Acme AI Tools",
    "identifier": "did:web:acme.com",
    "documentationUrl": "https://acme.com/docs",
    "logoUrl": "https://acme.com/logo.png"
  },
  "entries": [
    {
      "identifier": "urn:air:acme.com:tools:weather-reporter",
      "displayName": "Weather Reporter",
      "type": "application/mcp-server-card+json",
      "url": "https://api.acme.com/mcp",
      "description": "Retrieve real-time weather reports and forecasts.",
      "tags": [
        "weather",
        "climate",
        "forecasting"
      ],
      "capabilities": [
        "GetWeather",
        "GetForecast"
      ],
      "representativeQueries": [
        "what is the weather today",
        "check the rain forecast in New York"
      ],
      "version": "1.0.0",
      "updatedAt": "2026-07-07T00:00:00Z"
    }
  ]
}