# KI-Katalog

> 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.

Diese Prüfung meldet, ohne den Score zu verändern.

*Diese Leitfäden zur Behebung sind in englischer Sprache verfasst.*

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.

---

<a id="not-found"></a>

## 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"
    }
  ]
}
```

---

<a id="invalid-json"></a>

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

---

<a id="no-spec-version"></a>

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

---

<a id="no-host"></a>

## 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" }
```

---

<a id="empty"></a>

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

---

<a id="incomplete-entry"></a>

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

---

<a id="entry-type"></a>

## 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

---

<a id="dead-entry"></a>

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

---

<a id="entry-mistyped"></a>

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

---

Markdown-Darstellung von https://axrush.com/guides/ai-catalog