# Como preparar um site para agentes: llms.txt, páginas em Markdown, OpenAPI, api-catalog e MCP server cards

_2026-10-03 · O que um site pronto para agentes publica: llms.txt, páginas em Markdown, OpenAPI, o api-catalog da RFC 9727 e um MCP server card, com o shager.ai de exemplo._

Um site pronto para agentes oferece ao software um caminho curto e previsível entre "o que é isto?" e "como eu uso?". Na prática, isso se resume a cinco arquivos ou convenções: um resumo em `/llms.txt`, versões limpas em Markdown de cada página, uma descrição OpenAPI da API, um `/.well-known/api-catalog` no padrão RFC 9727 apontando para ela e um MCP server card que explica como se conectar. Nenhum deles é difícil de publicar. Juntos, permitem que um agente encontre, entenda e comece a usar um produto sem que uma pessoa precise colar URLs em um chat.

Vou usar o shager.ai como exemplo do começo ao fim, porque tudo o que está descrito aqui já está no ar nele, e você pode buscar cada arquivo com `curl` enquanto lê.

## Por que se dar ao trabalho, se nenhum buscador promete ler esses arquivos?

Primeiro, honestidade. O `llms.txt` é uma proposta, não um padrão ratificado, e não conheço nenhum grande provedor de modelos que tenha se comprometido publicamente a usá-lo na recuperação de informações. O api-catalog é uma RFC de verdade da IETF, e os MCP server cards são uma extensão aceita do MCP, mas a adoção por crawlers e clientes ainda está no começo.

O argumento para fazer mesmo assim é prático. Cada vez mais, os agentes chegam a um site porque uma pessoa mandou, do tipo "crie uma conta nisso e conecte". Nesse momento, o agente busca as páginas diretamente. Um site que responde em Markdown limpo, com uma descrição explícita da API e uma receita de conexão, é usado do jeito certo. Um site que responde com 400 KB de JavaScript vira um jogo de adivinhação.

## llms.txt: a porta de entrada

O formato está definido em [llmstxt.org](https://llmstxt.org/). É um arquivo Markdown em `/llms.txt` com um H1 que dá nome ao site (a única parte obrigatória), um resumo em citação (blockquote), texto livre opcional e seções H2 com listas de links acompanhados de notas curtas. Uma seção chamada "Optional" marca os links que o agente pode pular quando precisa de um contexto menor.

O arquivo do Shager segue esse formato. O começo é assim:

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

Algumas escolhas valem a cópia. A seção para agentes vem antes das páginas de marketing, porque um agente que lê o arquivo geralmente quer agir. Os preços aparecem em números simples no próprio arquivo, não atrás de um link. Os limites são ditos com clareza (por exemplo, os posts no TikTok ficam privados até o TikTok aprovar o app), para que o agente não prometa ao usuário algo que o produto ainda não faz. E há um `/llms-full.txt` complementar, com todo o conteúdo em um único arquivo, para os agentes que preferem uma busca só.

## Versões em Markdown de cada página

A mesma proposta sugere servir uma versão limpa em Markdown de cada página e recomenda anunciá-la com `rel="alternate"` e `type="text/markdown"`, além de um `rel="describedby"` apontando para o `llms.txt` que cobre a página. As duas coisas podem ser elementos HTML `<link>` ou um cabeçalho HTTP `Link`.

O Shager faz isso de duas formas. Cada página tem uma gêmea em Markdown sob `/md/`, então `/en/pricing` também está em `/md/en/pricing`. E uma requisição para a URL normal com `Accept: text/markdown` recebe o Markdown diretamente:

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

Toda página HTML também envia um cabeçalho `Link` anunciando as suas versões 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"
```

Um detalhe que importa para SEO: as respostas em Markdown levam `x-robots-tag: noindex`, para que os buscadores não indexem duas cópias de cada página. O Markdown é para os agentes; o HTML continua sendo a página canônica para pessoas e para os resultados de busca.

## OpenAPI: o contrato

Para tudo o que um agente vai chamar, um documento [OpenAPI](https://spec.openapis.org/oas/v3.1.0) ainda é a coisa mais útil que você pode publicar. Ele traz IDs de operação, parâmetros, schemas e autenticação em um formato que agentes e geradores de código conseguem ler.

O do Shager está em [app.shager.ai/api/v1/openapi.json](https://app.shager.ai/api/v1/openapi.json), na versão 3.1. Três convenções dele ajudam os agentes em particular. Os IDs de operação são iguais aos nomes das ferramentas MCP (`create_post`, `get_analytics`), então um agente que aprendeu uma interface já conhece a outra. Cada operação declara o escopo de chave exigido em uma extensão `x-scope`. E as descrições dos campos são escritas como instruções: por exemplo, a substituição de legenda em `per_channel` diz que é recomendável variar o texto em cada conta. Descrição é espaço de prompt; aproveite.

## api-catalog: dizendo ao software onde estão as APIs

A [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727), publicada pela IETF em junho de 2025, define uma URI conhecida, `/.well-known/api-catalog`, e uma relação de link `api-catalog`. Uma requisição a ela devolve um documento que lista as APIs de quem publica, com links para as descrições e a documentação de cada uma. A RFC exige o media type `application/linkset+json` para esse documento e usa relações de link como `service-desc`, para descrições legíveis por máquina como o OpenAPI, e `service-doc`, para a documentação voltada a pessoas.

Este é o catálogo completo do Shager:

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

Ele é curto porque o Shager tem uma única API. Uma empresa com várias listaria uma entrada por API. O link `rel="api-catalog"` no cabeçalho `Link` de cada página, mostrado acima, é o que permite a um cliente que cai em qualquer página encontrar o catálogo sem adivinhar o caminho.

## MCP server cards: como se conectar antes de se conectar

Um cliente MCP precisa saber onde o servidor está e como se autenticar antes de poder chamar `tools/list`. A [SEP-2127](https://modelcontextprotocol.io/seps/2127-mcp-server-cards) define os MCP Server Cards exatamente para isso: um documento JSON estático que descreve a identidade de um servidor remoto, os seus endpoints de transporte, os cabeçalhos obrigatórios e as versões de protocolo suportadas. A SEP reserva `<streamable-http-url>/server-card` como local recomendado e descreve a descoberta no nível do domínio por meio de um AI Catalog que aponta para os cards. O schema detalhado fica no repositório da extensão.

O Shager serve o seu card no local recomendado, `https://app.shager.ai/api/mcp/server-card`, e também em `https://shager.ai/.well-known/mcp/server-card.json`, um caminho que algumas ferramentas de descoberta testam. A parte de conexão diz:

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

O card também lista as ferramentas do Shager, cada uma com uma descrição de uma linha. Repare que a SEP deixa as ferramentas fora dos campos padrão do card de propósito, porque o que um servidor expõe pode variar conforme o usuário e a sessão. Trate qualquer lista de ferramentas em um card como uma prévia; a fonte da verdade é a chamada `tools/list` ao vivo.

## Dois extras: auth.md e um arquivo de skill

A descoberta diz ao agente o que existe. Mais dois arquivos dizem o que fazer.

O [/auth.md](/auth.md) é uma receita simples de como um agente obtém acesso: descobrir, se registrar com a chamada de autocadastro, usar a chave, entregar o link de reivindicação a uma pessoa e como essa pessoa revoga o acesso. Ele também deixa as regras claras: limite de requisições, formato dos erros, variação de legendas, só APIs oficiais. Um agente consegue segui-lo de cima a baixo.

O `https://shager.ai/skills/shager/SKILL.md` é um arquivo de skill no formato que o Claude Code usa para [skills](https://code.claude.com/docs/en/skills): frontmatter YAML com um `name` e uma `description` que diz ao modelo quando usá-la, seguidos de instruções numeradas. Instale e o agente passa a conhecer o fluxo do Shager sem precisar de um prompt longo. Como criar a sua própria versão está em [crie uma skill do Claude para o Shager](/en/blog/build-a-claude-skill-for-shager).

## Checklist para o seu próprio site

1. `/llms.txt` com um H1, um resumo de um parágrafo, a seção para agentes primeiro e indicações honestas para tudo o que ainda não está no ar.
2. Uma versão em Markdown de cada página, anunciada com `rel="alternate"` e `type="text/markdown"` e marcada como `noindex`.
3. Um documento OpenAPI com IDs de operação iguais aos das suas ferramentas MCP e descrições escritas como instruções.
4. `/.well-known/api-catalog` como `application/linkset+json`, com link a partir de cada página via `rel="api-catalog"`.
5. Um MCP server card em `<your MCP URL>/server-card`.
6. Uma receita de acesso em linguagem simples, como o `auth.md`, se os agentes puderem se cadastrar.

## Perguntas frequentes

### O llms.txt é a mesma coisa que o robots.txt?

Não. O `robots.txt` diz aos crawlers o que eles podem buscar. O `llms.txt` é um guia com curadoria do que vale a pena ler, escrito para modelos de linguagem. Ele não libera nem bloqueia nada.

### Publicar esses arquivos melhora o ranqueamento nas buscas?

Não há nenhuma evidência publicada de que melhore, e nenhum buscador disse que usa o `llms.txt` como sinal de ranqueamento. O valor está em os agentes usarem o seu produto do jeito certo quando chegam. Mantenha as páginas HTML fortes para SEO pelos próprios méritos.

### Preciso de um servidor MCP para aproveitar isso?

Não. `llms.txt`, páginas em Markdown, OpenAPI e um api-catalog são úteis para qualquer site com documentação ou API. O server card só se aplica se você tiver um servidor MCP remoto.

## Para onde ir agora

Busque os arquivos do Shager com `curl` e compare com o seu site. Para saber o que um agente faz depois da descoberta, a próxima parada é a [porta de entrada para agentes](/en/agents).

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