# Cómo preparar un sitio web para agentes: llms.txt, páginas en Markdown, OpenAPI, api-catalog y MCP Server Cards

_2026-10-03 · Qué publica un sitio listo para agentes: llms.txt, páginas en Markdown, OpenAPI, el api-catalog (RFC 9727) y una server card de MCP. Ejemplo: shager.ai._

Un sitio web preparado para agentes le ofrece al software un camino corto y predecible desde "¿qué es esto?" hasta "¿cómo lo uso?". En la práctica, eso se traduce en cinco archivos o convenciones: un resumen en `/llms.txt`, versiones limpias en Markdown de cada página, una descripción OpenAPI de la API, un `/.well-known/api-catalog` según el RFC 9727 que apunte a ella y una MCP server card que explique cómo conectarse. Ninguno es difícil de publicar. Juntos, permiten que un agente encuentre, entienda y empiece a usar un producto sin que una persona tenga que copiar URL en un chat.

Voy a usar shager.ai como ejemplo práctico de principio a fin, porque todas las piezas que describo aquí están publicadas y puedes descargar cada una con `curl` mientras lees.

## ¿Para qué hacerlo, si ningún motor promete leer estos archivos?

Primero, la verdad. `llms.txt` es una propuesta, no un estándar ratificado, y no conozco a ningún gran proveedor de modelos que se haya comprometido públicamente a usarlo en la recuperación de información. El api-catalog sí es un RFC real del IETF, y las MCP server cards son una extensión aceptada de MCP, pero su adopción por parte de rastreadores y clientes todavía es incipiente.

El argumento para hacerlo igual es práctico. Cada vez más, los agentes llegan a un sitio porque una persona se lo pidió, del tipo "regístrate aquí y conéctalo". En ese momento el agente descarga las páginas directamente. Un sitio que responde con Markdown limpio, una descripción explícita de la API y una receta de conexión se usa bien. Un sitio que responde con 400 KB de JavaScript obliga a adivinar.

## llms.txt: la puerta de entrada

El formato está definido en [llmstxt.org](https://llmstxt.org/). Es un archivo Markdown en `/llms.txt` con un H1 que nombra el sitio (la única parte obligatoria), un resumen en forma de cita, texto libre opcional y secciones H2 con listas de enlaces acompañados de notas breves. Una sección titulada "Optional" marca los enlaces que un agente puede saltarse cuando necesita un contexto más corto.

El archivo de Shager sigue esa estructura. El comienzo se ve así:

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

Hay algunas decisiones que vale la pena copiar. La sección para agentes va antes que las páginas de marketing, porque un agente que lee el archivo normalmente quiere actuar. Los precios aparecen en números concretos en el propio archivo, no detrás de un enlace. Las limitaciones se dicen sin rodeos (por ejemplo, que las publicaciones de TikTok quedan privadas hasta que TikTok apruebe la app), para que el agente no le prometa al usuario algo que el producto todavía no puede hacer. Y existe un `/llms-full.txt` complementario con todo el contenido en un solo archivo, para los agentes que prefieren una única descarga.

## Versiones en Markdown de cada página

La misma propuesta sugiere servir una versión limpia en Markdown de cada página y recomienda anunciarla con `rel="alternate"` y `type="text/markdown"`, además de `rel="describedby"` apuntando al `llms.txt` que cubre esa página. Ambas cosas pueden ir como elementos `<link>` de HTML o en una cabecera HTTP `Link`.

Shager lo hace de dos maneras. Cada página tiene un gemelo en Markdown bajo `/md/`, así que `/en/pricing` también está en `/md/en/pricing`. Y una solicitud a la URL normal con `Accept: text/markdown` recibe directamente el Markdown:

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

Además, cada página HTML envía una cabecera `Link` que anuncia sus alternativas:

```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 detalle importante para el SEO: las respuestas en Markdown llevan `x-robots-tag: noindex`, para que los buscadores no indexen dos copias de cada página. El Markdown es para los agentes; el HTML sigue siendo la página canónica para las personas y los resultados de búsqueda.

## OpenAPI: el contrato

Para todo lo que un agente vaya a llamar, un documento [OpenAPI](https://spec.openapis.org/oas/v3.1.0) sigue siendo lo más útil que puedes publicar. Ofrece los ID de operación, los parámetros, los esquemas y la autenticación en un formato que leen tanto los agentes como los generadores de código.

El de Shager está en [app.shager.ai/api/v1/openapi.json](https://app.shager.ai/api/v1/openapi.json), versión 3.1. Tres convenciones de ese documento ayudan especialmente a los agentes. Los ID de operación coinciden con los nombres de las herramientas MCP (`create_post`, `get_analytics`), así que un agente que aprendió una interfaz ya conoce la otra. Cada operación declara el permiso de clave que necesita en una extensión `x-scope`. Y las descripciones de los campos están escritas como instrucciones: por ejemplo, la del texto personalizado `per_channel` dice que se recomienda variar la redacción en cada cuenta. Las descripciones son espacio de prompt; aprovéchalas.

## api-catalog: decirle al software dónde están las API

El [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727), publicado por el IETF en junio de 2025, define una URI conocida, `/.well-known/api-catalog`, y una relación de enlace `api-catalog`. Una solicitud a esa URI devuelve un documento que lista las API de un editor con enlaces a sus descripciones y su documentación. El RFC exige el tipo de medio `application/linkset+json` para el documento y usa relaciones de enlace como `service-desc` para descripciones legibles por máquinas, como OpenAPI, y `service-doc` para la documentación pensada para personas.

Este es el catálogo de Shager, completo:

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

Es corto porque Shager tiene una sola API. Una empresa con varias incluiría una entrada por API. El enlace `rel="api-catalog"` que va en la cabecera `Link` de cada página, como se vio arriba, es lo que permite que un cliente que llega a cualquier página encuentre el catálogo sin adivinar la ruta.

## MCP server cards: cómo conectarse antes de conectarse

Un cliente MCP necesita saber dónde vive un servidor y cómo autenticarse antes de poder llamar a `tools/list`. El [SEP-2127](https://modelcontextprotocol.io/seps/2127-mcp-server-cards) define las MCP Server Cards precisamente para eso: un documento JSON estático que describe la identidad de un servidor remoto, sus endpoints de transporte, las cabeceras obligatorias y las versiones del protocolo que admite. El SEP reserva `<streamable-http-url>/server-card` como ubicación recomendada y describe un descubrimiento a nivel de dominio mediante un AI Catalog que enlaza a las cards. El esquema detallado vive en el repositorio de la extensión.

Shager sirve su card en la ubicación recomendada, `https://app.shager.ai/api/mcp/server-card`, y también en `https://shager.ai/.well-known/mcp/server-card.json`, una ruta que algunas herramientas de descubrimiento consultan. La parte de conexión dice:

```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 también lista las herramientas de Shager con una descripción de una línea. Ten en cuenta que el SEP deja las herramientas fuera de los campos estándar de la card a propósito, porque lo que expone un servidor puede variar según el usuario y la sesión. Toma cualquier lista de herramientas de una card como un adelanto; la fuente de verdad es la llamada `tools/list` en vivo.

## Dos extras: auth.md y un archivo de skill

El descubrimiento le dice a un agente qué existe. Dos archivos más le dicen qué hacer.

[/auth.md](/auth.md) es una receta sencilla de cómo un agente obtiene acceso: descubrir, registrarse con la llamada de alta propia, usar la clave, pasarle el enlace de reclamo a una persona, y cómo esa persona revoca el acceso. También enumera las reglas: límite de solicitudes, formato de los errores, variación de los textos, solo API oficiales. Un agente puede seguirla de principio a fin.

`https://shager.ai/skills/shager/SKILL.md` es un archivo de skill en el formato que usa Claude Code para las [skills](https://code.claude.com/docs/en/skills): frontmatter YAML con un `name` y una `description` que le dice al modelo cuándo usarla, y después instrucciones numeradas. Instálala y el agente conocerá el flujo de trabajo de Shager sin necesidad de un prompt largo. Cómo crear tu propia versión se explica en [crea una skill de Claude para Shager](/en/blog/build-a-claude-skill-for-shager).

## Lista de verificación para tu propio sitio

1. `/llms.txt` con un H1, un resumen de un párrafo, la sección para agentes primero y etiquetas honestas para todo lo que aún no esté disponible.
2. Una versión en Markdown de cada página, anunciada con `rel="alternate"` y `type="text/markdown"`, y marcada como `noindex`.
3. Un documento OpenAPI con ID de operación que coincidan con tus herramientas MCP y descripciones escritas como instrucciones.
4. `/.well-known/api-catalog` como `application/linkset+json`, enlazado desde cada página con `rel="api-catalog"`.
5. Una MCP server card en `<your MCP URL>/server-card`.
6. Una receta de acceso en lenguaje sencillo, como `auth.md`, si los agentes pueden registrarse.

## Preguntas frecuentes

### ¿llms.txt es lo mismo que robots.txt?

No. `robots.txt` les dice a los rastreadores qué pueden descargar. `llms.txt` es una guía seleccionada de lo que vale la pena leer, escrita para modelos de lenguaje. No concede ni niega nada.

### ¿Publicar estos archivos mejora el posicionamiento en buscadores?

No hay evidencia publicada de que lo haga, y ningún buscador ha dicho que use `llms.txt` como señal de posicionamiento. El valor está en que los agentes usen bien tu producto cuando llegan. Las páginas HTML tienen que ser sólidas para el SEO por mérito propio.

### ¿Necesito un servidor MCP para sacarle provecho a esto?

No. `llms.txt`, las páginas en Markdown, OpenAPI y un api-catalog son útiles para cualquier sitio con documentación o con una API. La server card solo aplica si tienes un servidor MCP remoto.

## Por dónde seguir

Descarga los archivos de Shager con `curl` y compáralos con los de tu sitio. Para saber qué hace un agente después del descubrimiento, la siguiente parada es el [punto de entrada para agentes](/en/agents).

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