ABERTO A OPORTUNIDADES EM TEMPO INTEGRAL (Disponível para começar imediatamente. Trabalho remoto preferencial no mundo todo.)// STACK:WORDPRESS E WOOCOMMERCEREACT E NEXT.JSTYPESCRIPTPERFORMANCE WEBINTEGRAÇÕES DE IAAUTOMAÇÃO (N8N, MAKE)// PROTOCOLO: MCP · JSON-RPC 2.0// STATUS: PRONTO PARA PRODUÇÃO
ABERTO A OPORTUNIDADES EM TEMPO INTEGRAL (Disponível para começar imediatamente. Trabalho remoto preferencial no mundo todo.)// STACK:WORDPRESS E WOOCOMMERCEREACT E NEXT.JSTYPESCRIPTPERFORMANCE WEBINTEGRAÇÕES DE IAAUTOMAÇÃO (N8N, MAKE)// PROTOCOLO: MCP · JSON-RPC 2.0// STATUS: PRONTO PARA PRODUÇÃO
HDRX
• 14 min de leitura
AEOMCPProduct EngineeringStructured DataAstro

Portfólios preparados para agentes: criando sites de desenvolvedores para MCP, LLMs e mecanismos de resposta

Um guia técnico para a arquitetura de portfólio em duas camadas: servidores MCP, llms.txt, agents.md e APIs estruturadas que tornam seu site legível para agentes de IA e mecanismos de resposta, e não apenas para visitantes humanos.

Uma parcela crescente do tráfego que chega aos portfólios de desenvolvedores não é de um recrutador rolando a página no celular — é de um agente. O Cursor consultando o site para verificar uma afirmação. Uma ferramenta de recrutamento usando Claude ou GPT-4 para classificar candidatos diante de uma descrição de vaga. O Perplexity ou o ChatGPT respondendo, em nome de uma pessoa, “quem é esta pessoa e o que ela construiu”, sem jamais renderizar seu CSS.

A maioria dos portfólios é construída exclusivamente para o primeiro tipo de visitante. Este post cobre a arquitetura para o segundo — os mecanismos concretos (MCP, llms.txt, agents.md, JSON-LD, endpoints REST estruturados) que tornam um site legível para máquinas, por que cada um existe e onde os trade-offs realmente pesam.

Por que a legibilidade por agentes é um problema de engenharia distinto

O SEO tradicional é otimizado para um crawler que busca HTML, extrai texto e links e o indexa para uma lista ranqueada de resultados que uma pessoa então acessa. O rastreamento agêntico tem um modelo de consumo inteiramente diferente:

  • O agente frequentemente tem um orçamento — um número fixo de chamadas de ferramenta, tokens ou carregamentos de página antes de precisar produzir uma resposta. Uma estrutura de página ineficiente custa diretamente tempo ao agente (e à pessoa esperando por ele).
  • O agente com frequência precisa sintetizar uma resposta, não apenas apontar para uma fonte. Se seus dados não puderem ser extraídos de forma limpa, ele alucina um resumo ou simplesmente ignora você.
  • Alguns agentes executam JavaScript e renderizam o DOM (agentes no estilo browser-use); outros não e apenas buscam HTML bruto ou chamam endpoints declarados (a maioria das ferramentas no estilo WebFetch e praticamente todos os crawlers por trás de produtos de chat em escala, por razões de custo). Apostar toda a sua encontrabilidade em renderização client-side exclui completamente o segundo grupo.
  • Agentes preferem cada vez mais chamar uma ferramenta declarada em vez de analisar prosa quando ela está disponível, porque saídas de ferramentas são estruturadas e tipadas, removendo toda uma classe de erros de extração. Esse é o verdadeiro argumento para expor um servidor MCP em vez de depender de o agente raspar sua página Sobre.

A implicação prática: a legibilidade de um portfólio por agentes não é um único artefato (como adicionar robots.txt) — é uma decisão arquitetural que atravessa estratégia de renderização, desenho de API e marcação estruturada.

A arquitetura em duas camadas

Este site implementa o que chamo de Arquitetura em Duas Camadas: um caminho de renderização otimizado para percepção e interação humanas, outro otimizado para consumo por máquinas, ambos sustentados por uma única fonte da verdade.

                        ┌────────────────────────┐
                        │     Domínio público     │
                        └────────────┬─────────────┘

                ┌────────────────────┴────────────────────┐
                ▼                                          ▼
       [ Camada humana ]                         [ Camada de agentes ]
       • Astro 5 SSG/SSR híbrido                  • Servidor MCP stateless (/api/mcp)
       • Navegação com sensação de SPA             • Arquivo de descoberta /llms.txt
       • HTML semântico + JSON-LD                  • Guia de contribuição /agents.md
       • Sistema de design, motion, imagens        • Endpoints REST (/api/resume, /api/projects)
                │                                          │
                └────────────────────┬─────────────────────┘

                         /src/data/*.ts (fonte única da verdade)

A restrição crítica que mantém isso sustentável: as duas camadas leem do mesmo módulo de dados tipado. A ferramenta get_projects do servidor MCP e o componente da página /projects usam o mesmo array projects.ts. Não há um “conteúdo para bots” separado que possa se desalinhar do “conteúdo para humanos” — uma falha comum em sites que acoplam um llms.txt como reflexão tardia e depois deixam de atualizá-lo quando o site visível muda.

Por que o modelo de saída híbrido do Astro importa aqui

O Astro entrega zero JavaScript por padrão e renderiza HTML estático em tempo de build, com a opção de incluir rotas específicas em renderização de servidor (output: "hybrid" com export const prerender = false por rota). Para a legibilidade por agentes isso importa por uma razão simples, mas decisiva: o conteúdo que existe na resposta HTML inicial é visível a todo consumidor, independentemente de executar JavaScript. Uma SPA React que monta conteúdo no cliente é invisível para qualquer agente que faça um fetch() simples — que, por razões de custo e latência, é a maioria deles.

As ilhas React (client:load, client:visible) são usadas aqui apenas para interatividade real — o filtro de projetos e o widget de chat — nunca para conteúdo que precisa ser descoberto. Isso não é antes de tudo uma otimização de performance; é uma decisão de arquitetura da informação que também melhora os Core Web Vitals.

Arquivos de descoberta: llms.txt e agents.md

O que o llms.txt realmente faz?

llms.txt é uma convenção proposta — não um padrão W3C ou IETF e não universalmente respeitada — para um arquivo Markdown simples na raiz do site que dá a um LLM um resumo curado e de alto sinal do site: o que ele é, as páginas principais e links para mais detalhes. É o análogo legível por máquina de um sitemap, mas escrito como prosa/Markdown para um modelo consumir diretamente, em vez de XML para um crawler enumerar.

Sua utilidade real hoje é mista, e vale ser honesto sobre isso:

Aspecto Realidade
Adoção por grandes produtos de IA Inconsistente — alguns crawlers o buscam; a maior parte dos mecanismos gerais de busca/resposta ainda não o prioriza como robots.txt ou sitemaps
Custo de implementação Quase zero — um arquivo Markdown estático
Modo de falha se estiver incorreto Silencioso — nenhum consumidor impõe schema, então um arquivo desatualizado apenas engana discretamente o agente que o ler
Melhor caso de uso atual Ferramentas de agentes que o verificam explicitamente (agentes de código, clientes MCP, integrações de ferramentas de desenvolvimento), e não a busca de IA voltada ao consumidor

Dado o baixo custo e a opcionalidade, vale publicar — mas não o trate como canal de descoberta garantido. É uma proteção, não infraestrutura.

agents.md — o README voltado para máquinas

agents.md (também visto como AGENTS.md) tem melhor adesão no mundo real porque agentes de programação (Claude Code, Cursor, Copilot Workspace etc.) procuram ativamente por ele como arquivo de instruções ao operar em um repositório ou projeto. Em um portfólio, seu papel é mais estreito que o da convenção no repositório: documentar como um agente deve interagir com a camada de agentes do site — URL do endpoint MCP, nomes das ferramentas e schemas de entrada, limites de taxa e operações com efeitos colaterais que exigem cuidado.

Conteúdo prático que vale incluir:

  • O endpoint de transporte MCP e a versão do protocolo.
  • Uma lista de ferramentas disponíveis com descrições de uma linha (o schema completo é descoberto pelo próprio protocolo — não o duplique e corra o risco de divergência).
  • Quais operações são somente leitura e quais têm efeitos colaterais (este site tem exatamente uma ferramenta com efeito colateral: contact, que envia um e-mail; todo o restante é somente leitura por desenho).
  • Limites de taxa e o comportamento esperado em erro, para que um agente integrador não precise fazer engenharia reversa dos modos de falha.

Preciso dos dois arquivos?

Sim, mas eles atendem a consumidores diferentes. llms.txt mira um agente que faz leitura ou sumarização geral do seu site. agents.md mira um agente (ou desenvolvedor) que quer agir — chamar suas ferramentas, integrar-se à sua API. Trate-os como uma camada de descoberta e uma camada de contrato de integração, respectivamente; não como duplicatas.

O servidor MCP: expondo um portfólio como ferramentas chamáveis

O Model Context Protocol (MCP) padroniza como um cliente LLM (Claude Desktop, Cursor, um agente customizado) descobre e chama ferramentas externas sobre uma interface consistente de JSON-RPC 2.0, em vez de cada integração inventar seu próprio formato de API e o modelo ter de receber sua semântica fora de banda via prompt engineering.

Em uma comparação REST/JSON-RPC, a proposta de valor real é:

  • Autodescritivo. Clientes MCP chamam um método de descoberta (tools/list) e recebem schemas tipados de cada ferramenta disponível, em tempo de execução, sem uma pessoa ler documentação de API e escrever um wrapper. Uma API REST comum exige um spec OpenAPI com cliente compatível ou integração escrita por humanos.
  • Invocação uniforme. Toda chamada e resposta de ferramenta segue o mesmo envelope JSON-RPC, independentemente do que a ferramenta faz internamente, permitindo que um único cliente MCP trabalhe com servidores MCP arbitrários sem código específico por servidor.
  • Nativo para modelos. A Anthropic e outros provedores treinam e otimizam seus harnesses de agentes especificamente para o padrão de chamadas MCP; assim, um portfólio exposto como ferramentas MCP é consumido de modo mais confiável por agentes baseados em Claude do que os mesmos dados em uma API REST não documentada, cuja semântica o modelo precisa inferir.

Formato do protocolo: JSON-RPC 2.0 sobre Streamable HTTP

O servidor deste site (src/pages/api/mcp.ts) implementa o transporte MCP atual — Streamable HTTP, um único endpoint POST que aceita objetos de requisição JSON-RPC 2.0 e pode responder com um payload JSON único ou um stream Server-Sent Events, substituindo o transporte HTTP+SSE anterior, de dois endpoints, das revisões mais antigas do protocolo. Uma requisição é assim:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_projects",
    "arguments": { "tags": ["ai", "mcp"], "featured": true }
  }
}

E a resposta:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "{ \"projects\": [ ... ] }" }
    ]
  }
}

Por que stateless e qual é o custo de fato

Servidores MCP podem ser stateful (guardando sessão e contexto conversacional no servidor) ou stateless (cada requisição é autossuficiente; não é necessária afinidade de sessão). Este servidor é deliberadamente stateless:

  • Deployabilidade. Um handler stateless executa de forma limpa em Vercel Edge Functions/funções serverless, sem armazenamento de sessão, roteamento sticky e com escala horizontal trivial — cada requisição pode cair em qualquer instância.
  • Simplicidade das ferramentas somente leitura. get_resume, get_projects, get_capabilities, check_availability e get_manifest não têm razão para lembrar chamadas anteriores; cada uma é uma função pura sobre a mesma fonte src/data/*.ts usada pelas páginas humanas.
  • O trade-off. Um desenho stateless não tem memória conversacional no servidor — qualquer contexto de múltiplas interações precisa ser transportado pelo cliente (reenviado a cada chamada) ou reconstruído do zero por requisição. Para a superfície de ferramentas de um portfólio, em que cada ferramenta é essencialmente uma leitura parametrizada, esse custo é desprezível. Ele não seria aceitável para uma ferramenta de workflow stateful (por exemplo, um fluxo de reserva em múltiplas etapas), por isso “meu servidor MCP deve ser stateless?” é uma decisão por superfície de ferramentas, e não uma regra geral.

A única ferramenta com efeito colateral: contact

Todas as outras ferramentas são somente leitura por desenho explícito — um agente avaliando um candidato jamais deveria conseguir modificar algo. contact é a exceção deliberada: ela valida e envia um e-mail por um provedor de e-mail transacional. Por ser a única superfície mutável, recebe escrutínio desproporcional:

  • Limites estritos de entrada (nome, meio de contato e tamanho da mensagem delimitados no servidor, não só no cliente).
  • Rate limiting no endpoint, independente do rate limiting aplicado ao restante da API, pois uma superfície com efeito colateral é o alvo mais valioso para abuso.
  • Nenhum stack trace ou detalhe interno devolvido em falha — erros são mapeados para códigos JSON-RPC genéricos.

Se você expõe um servidor MCP publicamente, a divisão leitura/escrita deve estar visível na documentação (agents.md) e ser reforçada no código, não apenas presumida. Um agente que opera de forma autônoma por uma pessoa chamará tudo que estiver chamável; o servidor é o único ponto de enforcement que importa.

MCP vs. REST comum vs. GraphQL — quando cada um faz sentido

REST comum GraphQL MCP
Descoberta Exige documentação externa (OpenAPI, README) Introspecção do schema tools/list nativo, parte do protocolo
Melhor consumidor Navegadores, outros serviços de backend Frontends que precisam de consultas flexíveis Agentes LLM / clientes compatíveis com MCP
Custo para adicionar uma operação Nova rota + atualização de docs Novo campo/resolver de schema Nova definição de ferramenta, autodescoberta
Adoção por provedores de modelos de IA Genérica — é preciso informar o formato aos modelos Genérica De primeira classe, feita para esse fim

A conclusão honesta: MCP não substitui REST; ele atende outro consumidor. Este site executa ambos — endpoints REST (/api/resume, /api/projects, /api/availability) para qualquer coisa que queira uma chamada HTTP convencional (incluindo agentes mais simples e ferramentas não MCP), e o servidor MCP para clientes que falam o protocolo nativamente. Manter ambos a partir da mesma camada de dados evita que isso vire dois sistemas para sincronizar.

Dados estruturados e HTML semântico para mecanismos de resposta

MCP e llms.txt cobrem agentes que buscam seu site ativamente ou chamam suas ferramentas. Uma grande fração do tráfego relevante para AEO nunca faz nenhum dos dois — é um mecanismo de busca ou resposta (AI Overviews do Google, Perplexity, Bing Copilot) que rastreia de modo convencional e extrai uma resposta da página renderizada. Esse consumidor precisa de sinais diferentes.

JSON-LD: a implementação concreta, não apenas “adicione dados estruturados”

Os tipos Person e ProfilePage do Schema.org (ou contexto adjacente a JobPosting se a página descreve disponibilidade para contratação) permitem que um crawler extraia entidades de forma determinística, em vez de inferi-las da prosa. Um exemplo mínimo e correto para a página sobre/inicial de um portfólio:

{
  "@context": "https://schema.org",
  "@type": "Person",
  "name": "Hendrix Garcia",
  "jobTitle": "Full-Stack Product Engineer",
  "url": "https://hdrx.com.br",
  "sameAs": [
    "https://github.com/TBD"
  ],
  "knowsAbout": [
    "React", "Astro", "TypeScript", "Model Context Protocol", "WordPress"
  ]
}

Duas coisas importam mais do que a escolha do schema em si:

  1. Precisão acima de completude. Não preencha sameAs, alumniOf ou knowsAbout com nada que não seja verdadeiro — dados estruturados são justamente o lugar em que a checagem automática de fatos contra a página visível é mais fácil para um crawler, e uma divergência é um sinal negativo mais forte que simplesmente omitir o campo.
  2. JSON-LD não substitui HTML semântico. Uma sopa de <div> com um bloco JSON-LD adicionado continua pior para acessibilidade, para crawlers que não entendem JSON-LD e para a pessoa que lê a página do que bons <article>, <section> e uma hierarquia de headings, com JSON-LD aplicado como reforço.

Estruturando conteúdo para extração de snippets em destaque e respostas

Mecanismos de resposta e snippets em destaque favorecem conteúdo em que uma resposta direta e autossuficiente aparece imediatamente abaixo de um heading formulado como pergunta, em vez de ficar dispersa num parágrafo ou exigir que o leitor (humano ou modelo) a infira. Na prática, para um portfólio ou blog técnico:

  • Use H3s formulados como perguntas reais onde a intenção de busca for realmente uma pergunta (“O que é MCP?”, “O Astro suporta SSR?”) — não como truque de keyword stuffing, apenas quando combinar com a intenção.
  • Coloque a resposta direta na primeira ou segunda frase após o heading. Nuances, exceções e ressalvas vêm depois, não misturadas antes.
  • Prefira listas e tabelas para tudo que for inerentemente estruturado (comparações, passos, especificações) — modelos de extração lidam com elas de forma mais confiável do que com enumeração em prosa.

Hierarquia de headings como primitivo de SEO e acessibilidade, não decoração

Um H1 por página (o title de frontmatter em uma configuração de blog Markdown/Astro), seguido de uma descida limpa H2 → H3 → H4 sem pular níveis. Vale repetir porque isso é violado com frequência por conteúdo otimizado visualmente em vez de semanticamente (por exemplo, usar H4 para um subtítulo porque “fica melhor” naquele tamanho, quando semanticamente é irmão de um H2). Saltos de nível prejudicam tanto a navegação de leitores de tela quanto os modelos de conteúdo baseados em headings que muitos pipelines de extração usam para construir o outline da página.

Rastreamento tradicional vs. rastreamento baseado em agentes — diferenças práticas

Dimensão Crawler tradicional (classe Googlebot) Rastreamento baseado em agentes (uso de ferramentas LLM)
Padrão de busca Amplo, agendado, indexa para ranquear depois Sob demanda, disparado por uma consulta específica, limitado por orçamento
Execução de JS Cada vez mais sim (Googlebot renderiza), mas com atraso e custo Varia muito por agente — muitos pulam JS por custo/latência
Formato de dados preferido HTML + dados estruturados (JSON-LD, meta tags) Dados estruturados quando presentes; caso contrário analisa HTML/Markdown; prefere uma ferramenta/API declarada
Métrica de sucesso para você Posição no ranking, taxa de clique Se a resposta sintetizada pelo agente sobre você é precisa e completa
Diretivas de robots robots.txt, X-Robots-Tag, meta robots — bem estabelecidas Ainda não há padrão consolidado; llms.txt é o análogo mais próximo, mas não universal

A consequência para a arquitetura: otimizar apenas para o Googlebot (dados estruturados, sitemap, tags canônicas) é necessário, mas insuficiente. Otimizar apenas para chamadas de ferramentas por agentes (MCP, llms.txt) deixa de fora o tráfego de mecanismos de resposta que ainda rastreia convencionalmente. Um portfólio que deve performar bem nos dois precisa das duas camadas — esse é todo o argumento da arquitetura em duas camadas descrita acima, em vez de escolher um paradigma.

Falhas comuns e solução de problemas

Um agente resume meu site de modo impreciso mesmo que a informação esteja correta na página

Verifique se o conteúdo relevante existe na resposta HTML bruta (curl na URL; não apenas visualize no navegador) ou só é renderizado no cliente depois da hidratação. Se for client-rendered, todo agente que não executa JavaScript vê uma casca vazia. Mova o conteúdo para uma rota pré-renderizada ou componente estático.

Meu servidor MCP funciona no Claude Desktop, mas outro cliente MCP não consegue conectar

Verifique o transporte. Clientes MCP antigos podem ainda esperar o transporte HTTP+SSE de dois endpoints, hoje descontinuado, em vez do atual Streamable HTTP de endpoint único. Confirme explicitamente tanto a versão de protocolo que seu servidor declara quanto a versão suportada pelo cliente, em vez de presumir compatibilidade.

llms.txt e o site visível se desalinharem

Isso é sintoma de tratar o arquivo de descoberta como conteúdo estático em vez de gerá-lo (ou ao menos suas seções com dados) a partir da mesma fonte (src/data/) que alimenta o restante do site. Qualquer cópia secundária e mantida manualmente dos dados acabará divergindo; a correção é arquitetural, não um lembrete para “atualizar mais”.

Os dados estruturados validam, mas não parecem influenciar como respostas de IA me descrevem

JSON-LD é um sinal, não garantia — mecanismos de resposta o ponderam junto com conteúdo em prosa, backlinks e suas próprias heurísticas de extração, e nada dessa ponderação é publicada ou estável. Nenhum provedor publica uma fórmula que ligue a presença de JSON-LD à inclusão em uma resposta gerada, então trate dados estruturados como fator de higiene que remove ambiguidade, não como uma alavanca de efeito mensurável previsível.

O rate limiting em /api/agent ou na ferramenta MCP contact está agressivo demais e bloqueia tráfego legítimo de agentes

Diferencie limites de taxa por risco de endpoint, não use um único limite global. Ferramentas somente leitura (get_resume, get_projects) podem aceitar chamadas mais frequentes de integrações legítimas; a ferramenta contact, com efeito colateral, deve permanecer rigorosamente limitada independentemente disso, pois seu custo de abuso (spam, esgotamento da cota de e-mail) é categoricamente diferente do de uma leitura chamada com frequência.

FAQ técnico

Qual é a diferença entre MCP e uma API REST?

MCP é um protocolo sobre JSON-RPC 2.0 que padroniza descoberta e invocação de ferramentas para clientes LLM — um cliente pode chamar tools/list e receber schemas tipados de cada operação disponível em tempo de execução. Uma API REST comum não tem mecanismo equivalente de autodescrição; um modelo ou desenvolvedor precisa de documentação externa (ou de um spec OpenAPI com tooling) para saber o que pode chamar e como.

llms.txt melhora o ranking na busca do Google?

Não. llms.txt não é um sinal reconhecido pelo algoritmo de ranking da busca tradicional do Google. Ele visa ferramentas baseadas em LLM que escolham lê-lo, um canal separado do ranking SEO convencional. Fundamentos de SEO tradicional (dados estruturados, HTML semântico, velocidade de página, backlinks) continuam sendo o que move o ranking no Google.

Um servidor MCP deve ser stateful ou stateless?

Use stateless por padrão para superfícies de ferramentas somente leitura — ele simplifica o deploy (sem afinidade de sessão), escala trivialmente em infraestrutura serverless/edge e corresponde ao padrão de acesso da maior parte dos dados de portfólio (leituras parametrizadas de um dataset fixo). Escolha stateful apenas quando uma ferramenta realmente precisar de contexto de múltiplas etapas no servidor, como um workflow que abrange várias chamadas e não pode ser reconstruído a partir dos parâmetros de uma única requisição.

Um agente de IA pode chamar uma ferramenta MCP com efeitos colaterais sem confirmação da pessoa usuária?

Isso depende da política de confirmação do próprio cliente MCP, não do servidor — a única responsabilidade do servidor é tornar ferramentas com efeitos colaterais claramente distinguíveis (nome, documentação e, idealmente, uma anotação readOnlyHint quando o protocolo a suportar), para que um cliente bem-comportado possa controlá-las adequadamente. Servidores bem projetados ainda minimizam a superfície de efeitos colaterais para reduzir o blast radius, independentemente do cliente, já que nem todo cliente aplica confirmação de modo consistente.

Astro SSG ou SSR é melhor para legibilidade por agentes?

Geração estática (SSG) garante que a página completa exista como HTML no momento da requisição, sem computação de servidor — a base mais segura para qualquer consumidor que apenas busque HTML bruto. Renderização no servidor (SSR) é necessária para conteúdo realmente dinâmico (como uma checagem de disponibilidade ao vivo), mas adiciona dependência de runtime; se esse runtime for lento ou falhar, agentes que não tentam novamente podem ver uma página incompleta. O modelo híbrido do Astro — estático por padrão, SSR opt-in por rota — permite que cada rota escolha a garantia correta em vez de impor um trade-off global.

O que é JSON-RPC 2.0 e por que MCP o usa?

JSON-RPC 2.0 é uma especificação leve e agnóstica a transporte para chamada remota de procedimentos: uma requisição carrega nome de método, parâmetros e id; uma resposta traz o id correspondente com resultado ou erro estruturado. MCP o adotou porque é simples de implementar em qualquer linguagem, tem semântica de erro bem definida (códigos numéricos, não uma disputa de status HTTP ad hoc) e não vincula o protocolo à semântica HTTP como uma abordagem puramente REST faria — importante porque MCP também suporta transportes como stdio para comunicação local entre processos.

Preciso de llms.txt e agents.md, ou um é redundante?

Eles não são redundantes — llms.txt é um arquivo geral de descoberta/resumo para qualquer LLM que leia sobre seu site, enquanto agents.md é um contrato de integração para um agente que queira chamar especificamente suas ferramentas ou APIs. Um site apenas com llms.txt dá ao agente uma descrição, mas nenhuma interface acionável; um site apenas com agents.md presume que o agente já sabe procurar por ele. Publicar ambos custa pouco e atende consumidores realmente diferentes.

Como testo se meu servidor MCP realmente funciona antes de publicá-lo?

Envie requisições JSON-RPC brutas diretamente ao endpoint (curl com envelope JSON-RPC ou um script mínimo) para verificar se tools/list devolve schemas corretos e se tools/call retorna resultados bem formados para cada ferramenta, independentemente de um cliente específico. Depois teste com pelo menos um cliente MCP real (Claude Desktop ou equivalente) para detectar problemas de nível de transporte — incompatibilidades de versão de protocolo ou de streaming — que uma requisição bruta não captura, pois implementações de clientes variam no rigor com que aplicam o spec.

Adicionar dados estruturados JSON-LD garante que meu site apareça em respostas geradas por IA?

Não — dados estruturados reduzem a ambiguidade no que um crawler ou modelo extrai, mas nenhum provedor publica garantia ou fórmula que vincule a presença de JSON-LD à inclusão em uma resposta gerada. Trate-o como remoção de uma fonte de erro de extração, não como alavanca de ranking com efeito previsível.

Dúvidas ou ideias de projeto?

Entre em contato para falar sobre arquitetura, otimização ou agentes de IA.

Entrar em contato →