Ces guides de correction sont rédigés en anglais.

Catalogue IA

Cette vérification signale sans modifier le score.

How to publish an agent resource catalog: ai-catalog.json and ard.json, entry types, and why an entry pointing at nothing is worse than no catalog.

One file that names every machine-readable thing your site offers: an MCP server, an A2A agent card, another catalog. Instead of an agent probing half a dozen well-known paths and guessing, it reads one index.

Two drafts, neither settled

The Linux Foundation Agent Card working group specifies /.well-known/ai-catalog.json; Agentic Resource Discovery specifies /.well-known/ard.json. They overlap heavily and neither has won, so this check accepts both and never scores you down for the absence. Publishing one is a bet; the cost is a small static file.

No agent resource catalog found

Nothing at either well-known path, and no Link header or <link> tag pointing at one. If you publish no MCP server, agent card or API, there is nothing to index and nothing to do.

GET /.well-known/ai-catalog.json

{
  "specVersion": "0.1",
  "host": { "identifier": "example.com", "displayName": "Example" },
  "entries": [
    {
      "identifier": "example-mcp",
      "type": "application/mcp-server-card+json",
      "displayName": "Example MCP server",
      "url": "https://example.com/.well-known/mcp/server-card.json"
    }
  ]
}

The catalog is not valid JSON

The file is served and does not parse. The usual causes are a trailing comma, a comment, or an HTML error page returned with a 200. Fetch it yourself and read the first line; if it starts with <!doctype the route is not what you think it is.

The catalog declares no specVersion

Both specifications are drafts and both are moving. Without specVersion, a reader cannot tell which revision the shape follows and has to guess from the fields present.

The catalog declares no host

The host object names whose catalog this is. It matters because a catalog can be copied, mirrored or nested inside another, and an entry with no owner is an entry nobody can verify.

"host": { "identifier": "example.com", "displayName": "Example" }

An empty catalog

The file is valid and lists nothing. That is worse than no file: an agent spent a request to learn that you index nothing. Either list what you have or remove it.

An entry missing a required field

Every entry needs an identifier, a type, a displayName, and exactly one of url or data: either say where the document lives or inline it, not both and not neither.

An unrecognised entry type

The draft defines three media types. An entry outside them is skipped by a reader that validates, which means the resource is listed and still invisible.

application/mcp-server-card+json
application/a2a-agent-card+json
application/ai-catalog+json for a nested catalog

An entry pointing at a document that cannot be fetched

This is the failure that makes a catalog worse than nothing. An index naming a resource that answers nothing sends every agent that trusts it to a dead URL, and it will keep doing so until somebody notices.

The common causes are a relative URL that resolves against the wrong base, a staging hostname, and a file moved without updating the index. Fetch every url in your own catalog from outside your network before shipping it.

An entry served as a different type than it claims

The entry declares one media type and the document answers with another, usually application/json where a specific type was promised. A reader dispatching on content type will not recognise it.

# the entry says
"type": "application/mcp-server-card+json"

# so the document should answer
Content-Type: application/mcp-server-card+json; charset=utf-8