# Rendre un site lisible par les agents IA : llms.txt, pages Markdown, OpenAPI, api-catalog et MCP Server Cards

_2026-10-03 · Ce que publie un site prêt pour les agents : llms.txt, pages Markdown, OpenAPI, api-catalog (RFC 9727) et MCP server card, avec shager.ai en exemple._

Un site prêt pour les agents offre aux logiciels un chemin court et prévisible entre « qu'est-ce que c'est ? » et « comment je m'en sers ? ». Concrètement, cela passe par cinq fichiers ou conventions : un résumé `/llms.txt`, une version Markdown propre de chaque page, une description OpenAPI de l'API, un `/.well-known/api-catalog` conforme à la RFC 9727 qui pointe vers elle, et une MCP server card qui décrit comment se connecter. Aucun n'est difficile à publier. Ensemble, ils permettent à un agent de trouver un produit, de le comprendre et de commencer à l'utiliser sans qu'un humain ait à copier des URL dans une conversation.

Je prendrai shager.ai comme exemple tout au long de l'article, parce que chacun des éléments décrits ici y est en ligne : vous pouvez les récupérer un par un avec `curl` au fil de la lecture.

## Pourquoi s'en donner la peine, si aucun moteur ne promet de lire ces fichiers ?

Soyons honnêtes d'emblée. `llms.txt` est une proposition, pas un standard ratifié, et je n'ai connaissance d'aucun grand fournisseur de modèles qui se soit publiquement engagé à l'utiliser pour la recherche d'informations. L'api-catalog est une vraie RFC de l'IETF, et les MCP server cards sont une extension MCP acceptée, mais leur adoption par les robots d'indexation et les clients n'en est qu'à ses débuts.

Les raisons de s'y mettre malgré tout sont pratiques. De plus en plus, les agents arrivent sur un site parce qu'une personne le leur a demandé, du type « inscris-toi et connecte-le ». À ce moment-là, l'agent récupère directement les pages. Un site qui répond en Markdown propre, avec une description explicite de son API et une marche à suivre pour s'y connecter, est utilisé correctement. Un site qui répond avec 400 Ko de JavaScript oblige l'agent à deviner.

## llms.txt : la porte d'entrée

Le format est défini sur [llmstxt.org](https://llmstxt.org/). Il s'agit d'un fichier Markdown placé à `/llms.txt`, avec un titre H1 qui nomme le site (la seule partie obligatoire), un résumé sous forme de citation, un texte libre facultatif, et des sections H2 contenant des listes de liens accompagnés de courtes notes. Une section intitulée « Optional » signale les liens qu'un agent peut ignorer quand il a besoin d'un contexte plus court.

Le fichier de Shager respecte cette structure. Voici à quoi ressemble le début :

```markdown
# Shager

> Shager (שגר) is agent-first distribution infrastructure for agencies and
> marketers: your agent creates, Shager ships it everywhere. ...

## For AI agents
- MCP server: https://app.shager.ai/api/mcp (OAuth sign-in for any MCP client that supports it, or Authorization: Bearer <api key>)
- REST API: https://app.shager.ai/api/v1 ...
- Self sign-up: POST https://app.shager.ai/api/v1/agent/signup ...
```

Quelques choix méritent d'être repris. La section destinée aux agents précède les pages marketing, parce qu'un agent qui lit ce fichier veut généralement agir. Les tarifs figurent en chiffres dans le fichier lui-même, et non derrière un lien. Les limites sont énoncées clairement (par exemple, les publications TikTok restent privées tant que TikTok n'a pas validé l'application), pour qu'un agent ne promette pas à un utilisateur ce que le produit ne sait pas encore faire. Enfin, un fichier compagnon, `/llms-full.txt`, rassemble tout le contenu en un seul fichier pour les agents qui préfèrent une requête unique.

## Une version Markdown de chaque page

La même proposition suggère de servir une version Markdown propre de chaque page, et recommande de la signaler avec `rel="alternate"` et `type="text/markdown"`, ainsi qu'avec `rel="describedby"` pointant vers le `llms.txt` qui couvre la page. Les deux peuvent prendre la forme d'éléments HTML `<link>` ou d'un en-tête HTTP `Link`.

Shager le fait de deux manières. Chaque page a un double en Markdown sous `/md/` : `/en/pricing` existe aussi à `/md/en/pricing`. Et une requête vers l'URL normale avec `Accept: text/markdown` reçoit directement le Markdown :

```bash
curl -s -H "Accept: text/markdown" https://shager.ai/en/pricing | head -5
```

Chaque page HTML envoie aussi un en-tête `Link` qui annonce ses versions alternatives :

```http
link: </.well-known/api-catalog>; rel="api-catalog",
      </llms.txt>; rel="describedby"; type="text/plain",
      </md/en/agents>; rel="alternate"; type="text/markdown"
```

Un détail compte pour le référencement : les réponses en Markdown portent `x-robots-tag: noindex`, pour que les moteurs de recherche n'indexent pas deux copies de chaque page. Le Markdown est destiné aux agents ; la page HTML reste la version canonique pour les internautes et les résultats de recherche.

## OpenAPI : le contrat

Pour tout ce qu'un agent va appeler, un document [OpenAPI](https://spec.openapis.org/oas/v3.1.0) reste ce que vous pouvez publier de plus utile. Il fournit les identifiants d'opérations, les paramètres, les schémas et l'authentification sous une forme que lisent aussi bien les agents que les générateurs de code.

Celui de Shager se trouve à [app.shager.ai/api/v1/openapi.json](https://app.shager.ai/api/v1/openapi.json), en version 3.1. Trois conventions y aident particulièrement les agents. Les identifiants d'opérations correspondent aux noms des outils MCP (`create_post`, `get_analytics`) : un agent qui connaît une interface connaît donc l'autre. Chaque opération déclare le scope de clé qu'elle exige dans une extension `x-scope`. Et les descriptions des champs sont rédigées comme des consignes : par exemple, celle de la légende personnalisée `per_channel` indique qu'il est recommandé de varier la formulation d'un compte à l'autre. Les descriptions, c'est de l'espace de prompt ; servez-vous-en.

## api-catalog : indiquer aux logiciels où se trouvent les API

La [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727), publiée par l'IETF en juin 2025, définit une URI bien connue, `/.well-known/api-catalog`, ainsi qu'une relation de lien `api-catalog`. Une requête vers cette adresse renvoie un document qui recense les API d'un éditeur, avec des liens vers leurs descriptions et leur documentation. La RFC impose le type de média `application/linkset+json` pour ce document et utilise des relations de lien comme `service-desc`, pour les descriptions lisibles par une machine telles qu'OpenAPI, et `service-doc`, pour la documentation destinée aux humains.

Voici le catalogue de Shager, dans son intégralité :

```json
{
  "linkset": [
    {
      "anchor": "https://app.shager.ai/api/v1",
      "service-desc": [
        { "href": "https://app.shager.ai/api/v1/openapi.json", "type": "application/openapi+json" }
      ],
      "service-doc": [
        { "href": "https://shager.ai/en/agents", "type": "text/html" },
        { "href": "https://shager.ai/md/en/agents", "type": "text/markdown" }
      ]
    }
  ]
}
```

Il est court, parce que Shager n'a qu'une API. Une entreprise qui en a plusieurs ajouterait une entrée par API. Le lien `rel="api-catalog"` présent dans l'en-tête `Link` de chaque page, montré plus haut, permet à un client qui arrive sur n'importe quelle page de trouver le catalogue sans deviner le chemin.

## MCP server cards : savoir comment se connecter avant de se connecter

Un client MCP doit savoir où se trouve un serveur et comment s'authentifier avant de pouvoir appeler `tools/list`. La [SEP-2127](https://modelcontextprotocol.io/seps/2127-mcp-server-cards) définit les MCP Server Cards précisément pour cela : un document JSON statique qui décrit l'identité d'un serveur distant, ses points d'accès de transport, les en-têtes requis et les versions du protocole prises en charge. La SEP réserve `<streamable-http-url>/server-card` comme emplacement recommandé et décrit une découverte au niveau du domaine, via un AI Catalog qui renvoie vers les cards. Le schéma détaillé se trouve dans le dépôt de l'extension.

Shager sert sa card à l'emplacement recommandé, `https://app.shager.ai/api/mcp/server-card`, ainsi qu'à `https://shager.ai/.well-known/mcp/server-card.json`, un chemin que certains outils de découverte interrogent. La partie consacrée à la connexion se présente ainsi :

```json
{
  "name": "ai.shager/shager",
  "title": "Shager",
  "version": "1.0.0",
  "remotes": [
    {
      "type": "streamable-http",
      "url": "https://app.shager.ai/api/mcp",
      "headers": [
        { "name": "Authorization", "isRequired": true, "isSecret": true,
          "description": "Bearer shgr_… API key (self-signup: POST /api/v1/agent/signup)" }
      ]
    }
  ]
}
```

La card liste aussi les outils de Shager, avec une description d'une ligne pour chacun. Notez que la SEP exclut volontairement les outils des champs standard de la card, car ce qu'un serveur expose peut varier selon l'utilisateur et la session. Considérez toute liste d'outils figurant dans une card comme un aperçu : c'est l'appel `tools/list` en direct qui fait foi.

## Deux bonus : auth.md et un fichier de skill

La découverte indique à un agent ce qui existe. Deux autres fichiers lui disent quoi faire.

[/auth.md](/auth.md) est une marche à suivre en clair qui explique comment un agent obtient un accès : découvrir, s'inscrire avec l'appel d'auto-inscription, utiliser la clé, transmettre le lien de revendication à un humain, et comment cet humain révoque l'accès. Le fichier énonce aussi les règles : limite de requêtes, format des erreurs, variation des légendes, API officielles uniquement. Un agent peut le suivre du début à la fin.

`https://shager.ai/skills/shager/SKILL.md` est un fichier de skill au format qu'utilise Claude Code pour ses [skills](https://code.claude.com/docs/en/skills) : un en-tête YAML avec un `name` et une `description` qui indique au modèle quand s'en servir, suivi d'instructions numérotées. Installez-le, et l'agent connaît le fonctionnement de Shager sans long prompt. Pour créer votre propre version, consultez notre article [créer une skill Claude pour Shager](/fr/blog/build-a-claude-skill-for-shager).

## Une checklist pour votre propre site

1. Un `/llms.txt` avec un titre H1, un résumé d'un paragraphe, la section destinée aux agents en premier, et des mentions honnêtes pour tout ce qui n'est pas encore en ligne.
2. Une version Markdown de chaque page, signalée avec `rel="alternate"` et `type="text/markdown"`, marquée `noindex`.
3. Un document OpenAPI dont les identifiants d'opérations correspondent à vos outils MCP, avec des descriptions rédigées comme des consignes.
4. Un `/.well-known/api-catalog` en `application/linkset+json`, référencé depuis chaque page avec `rel="api-catalog"`.
5. Une MCP server card à `<your MCP URL>/server-card`.
6. Une marche à suivre en langage clair comme `auth.md`, si des agents peuvent s'inscrire.

## FAQ

### llms.txt, c'est la même chose que robots.txt ?

Non. `robots.txt` indique aux robots ce qu'ils ont le droit de récupérer. `llms.txt` est un guide sélectif de ce qui vaut la peine d'être lu, rédigé pour les modèles de langage. Il n'accorde et n'interdit rien.

### Publier ces fichiers améliore-t-il le référencement ?

Aucune donnée publiée ne le montre, et aucun moteur de recherche n'a déclaré utiliser `llms.txt` comme critère de classement. L'intérêt, c'est que les agents utilisent correctement votre produit une fois arrivés chez vous. Faites en sorte que vos pages HTML soient solides pour le référencement par elles-mêmes.

### Faut-il un serveur MCP pour en tirer parti ?

Non. `llms.txt`, les pages Markdown, OpenAPI et un api-catalog sont utiles à tout site qui propose une documentation ou une API. La server card ne concerne que ceux qui font tourner un serveur MCP distant.

## Pour aller plus loin

Récupérez les fichiers de Shager avec `curl` et comparez-les à ceux de votre propre site. Pour savoir ce que fait un agent après la découverte, rendez-vous sur le [point d'entrée des agents](/fr/agents).

---
Source: https://shager.ai/fr/blog/agent-ready-websites-llms-txt