Opens in a new tabSkip to content
Agent LighthouseAgent Lighthouse

    Searches the text of every published page. The evidence sources themselves are not in this index — search all of them on the trusted sources page.

    GitHub ↗
    Browse checks and page contents
    agent-interfaces/ai-catalog-exists

    AI Catalog exists

    What it checks

    The AI catalog is the central discovery file that tells AI agents what capabilities your site offers. Think of it as a table of contents for your APIs, tools, and services. Without it, agents must probe multiple endpoints to understand what your site can do.

    Why it matters

    Publishing a JSON document at {site}/…/ai-catalog.json that lists MCP Server Card entries (type application/mcp-server-card+json) causes MCP clients performing domain-level discovery to find and connect to the site’s MCP server without manual URL entry.

    Evidence

    mcp-discovery-ai-catalog-well-known

    This is the path the MCP project itself is converging on. SEP-2127 (opened 2026-01-21, label ‘in-review’, still OPEN and unmerged as of 2026-08-11) delegates domain-level discovery to an ‘AI Catalog’ and its extension repo’s docs/discovery.md states: ‘An AI Catalog MAY be served from any URL. For automated domain-level discovery, hosts MAY publish one at: /.well-known/ai-catalog.json. Clients performing domain-level discovery SHOULD attempt to retrieve this well-known URL.’ Media type SHOULD be application/ai-catalog+json; MCP entries use type application/mcp-server-card+json and urn:air: identifiers.

    Real conformant deployments exist and verified live on 2026-08-20: vercel.com serves it with the exact application/ai-catalog+json media type and specVersion 1.0; zapier.com serves specVersion 1.0 with a trustManifest and an entry pointing at its MCP server card. The underlying AI Catalog repo (Agent-Card/ai-catalog, 210 stars) was pushed the same day it was checked, so the work is live. Audit guidance: check /.well-known/ai-catalog.json, validate specVersion + entries[].type + entries[].url, require a JSON content-type (reject HTML 200 soft-404s), and prefer application/ai-catalog+json.

    Path and schema (ARD v0.91, verified 2026-10-18): ARD v0.91 moved the normative well-known path to /.well-known/ard.json on 2026-08-26 (§5.1: a consumer “MUST fetch /.well-known/ard.json”; the predecessor /.well-known/ai-catalog.json “MAY additionally” be consulted) — github.com/…/ard.md. Its ArdManifest schema requires only entries. specVersion and host come from the Linux Foundation AI Catalog spec and are optional under ARD. The one documented consumer, hf-discover, still resolves only ai-catalog.json and reads only entries; it never reads specVersion or host — raw.githubusercontent.com/…/navigation.py. The MCP Server Card extension (SEP-2127) also still names ai-catalog.json. The two paths therefore conflict, and both have a reader, so the audit accepts either.

    Counter-evidence: The SEP is not merged — nothing about this is in the ratified spec (current revision 2026-07-28). ai-catalog.json is not in the IANA Well-Known URIs registry (106 entries on 2026-10-18; mcp, mcp.json, ai-catalog.json, webmcp, openapi are all absent). The MCP extension repo carrying the discovery text had 10 stars on 2026-10-18. No MCP client vendor documents consuming it. Anthropic’s own docs say ‘You can manually add any third-party connector to Claude as long as you have the URL of that remote MCP server’.

    OpenAI’s Apps SDK routes through a developer-mode URL paste, plus ‘public plugin submission’ with ‘domain verification’. A probe of 19 major domains found only 2 publishers, both large SaaS vendors. SEP-2127 itself lists ‘No Domain-Level Discovery’ as an unsolved pain point, which is an admission that the mechanism does not yet work.

    Limits

    A well-known path whose request got no HTTP response, because it was not sent, timed out, failed in transport or ended in a redirect loop, is not read. When no manifest is found and a path was not read, the audit returns not applicable with the cause instead of reporting the catalog as absent. Both paths must answer without a manifest before absence is reported.

    Sources