Atualizado: 7 de novembro de 2026. Detalhes de MCP e OAuth conferidos no servidor ao vivo, versão 1.5.1.
Um agente de IA que chega a um site tem o mesmo problema de um desenvolvedor novo: o que é isto, o que posso chamar e como me autentico? Em 2026 existe um pequeno conjunto de arquivos convencionais que respondem exatamente a isso: llms.txt, alguns descritores em /.well-known/ e um manifesto de agent skills. A TronSave publica todos eles. Este é um tour pelo que há em cada um, por que ele existe e pela única regra que nenhum desses arquivos consegue impor.
llms.txt: o resumo para ler
O llms.txt fica na raiz de um site e faz pelos modelos de linguagem o que um bom README faz por um desenvolvedor: um parágrafo dizendo o que é aquilo e, em seguida, links selecionados com uma frase de contexto cada. É Markdown, não um schema, e essa é a ideia: ele foi feito para ser lido, não parseado.
O da TronSave tem quatro seções. Um resumo do produto em uma linha. Páginas principais — início, mercado, ferramentas, FAQ —, cada uma com uma descrição do que realmente há ali. Um bloco Desenvolvedores e agentes de IA com links para a referência da API, o catálogo de APIs, a server card do MCP, o índice de agent skills e o documento de autenticação. E Jurídico: termos, privacidade e aviso de risco.
A disciplina útil aqui é a curadoria. Um sitemap lista todas as URLs; o llms.txt lista as dez que importam e diz por quê. Se o seu arquivo precisa de barra de rolagem, ele deixou de cumprir seu papel.
O diretório .well-known
Enquanto o llms.txt é texto corrido, o /.well-known/ é legível por máquinas. São cinco arquivos, cada um respondendo a uma pergunta diferente:
| Arquivo | Padrão | Responde |
|---|---|---|
api-catalog |
RFC 9727 | Quais APIs existem aqui e onde estão suas descrições? |
oauth-protected-resource |
RFC 9728 | Qual é o recurso protegido e como as credenciais são enviadas? |
mcp/server-card.json |
MCP | Onde está o servidor MCP, qual transporte, qual autenticação? |
agent-skills/index.json |
agentskills.io | Quais skills empacotadas um agente pode carregar? |
security.txt |
RFC 9116 | Com quem eu falo sobre uma vulnerabilidade? |
api-catalog: a separação entre máquina e pessoa
A RFC 9727 define um linkset: cada API recebe uma âncora e, depois, links que a descrevem. A TronSave publica duas âncoras — a API REST v2 e o endpoint MCP — e cada uma traz tanto um service-desc quanto um service-doc:
{
"linkset": [
{
"anchor": "https://api.tronsave.io/v2",
"service-desc": [ { "href": ".../api-reference.md", "type": "text/markdown" } ],
"service-doc": [ { "href": ".../api-reference", "type": "text/html" } ]
},
{
"anchor": "https://mcp.tronsave.io/mcp",
"service-desc": [ { "href": ".../mcp/server-card.json", "type": "application/json" } ],
"service-doc": [ { "href": ".../api-reference/mcp", "type": "text/html" } ]
}
]
}
O valor está nessa distinção. service-doc é a página HTML que uma pessoa lê. service-desc é a descrição legível por máquinas: aqui, Markdown para a referência REST e JSON para a card do MCP. Um agente segue o service-desc e pula todo o invólucro de marketing.
oauth-protected-resource: API keys primeiro, OAuth para o MCP
Metadados RFC 9728 costumam acompanhar uma implantação OAuth. A API REST da TronSave em si não tem fluxo OAuth — suas credenciais principais são uma API key ou uma assinatura de carteira —, mas o tronsave.io publica o descritor mesmo assim: ele nomeia o recurso, seu servidor de autorização e seus scopes, aponta para a documentação e informa que as credenciais bearer vão em um cabeçalho, com os metadados oauth-authorization-server correspondentes ao lado. Um cliente que procura esses arquivos encontra uma resposta em vez de um 404. O servidor MCP vai além: desde 7 de novembro de 2026, o mcp.tronsave.io oferece um login OAuth real para o endpoint https://mcp.tronsave.io/oauth/mcp, com seus próprios metadados de recurso protegido e um servidor de autorização (authorization code com PKCE, refresh tokens e um endpoint de registro de clientes). É assim que apps como Claude e Cursor se conectam: o usuário entra em uma página da TronSave com uma API key ou uma assinatura de carteira, e a partir daí o app fica autenticado.
auth.md: a resposta honesta para serviços sem OAuth
Como a API REST não tem fluxo OAuth a ser descoberto, a autenticação de verdade é descrita em um auth.md autossuficiente. Ele é específico exatamente onde isso economiza tempo de quem integra:
- A API REST recebe sua chave em um cabeçalho
apikeyem minúsculas. - O servidor MCP a recebe em um cabeçalho
authorizationcom o esquemaApiKey. - Uma assinatura de carteira TRON é o terceiro caminho, e o documento deixa claro que você nunca envia uma chave privada, apenas a assinatura.
As duas primeiras são uma armadilha de verdade: a mesma credencial, dois cabeçalhos diferentes e duas grafias diferentes, dependendo da interface que você chama. Deixar isso por escrito é a diferença entre uma integração de cinco minutos e uma tarde inteira de erros 401.
O arquivo também admite o que não existe. Não há um endpoint OAuth de registro dinâmico para obter uma API key de forma programática (o login OAuth do servidor MCP, que é separado, tem seu próprio endpoint de registro para apps cliente), então ele explica como uma pessoa obtém uma chave: conectando uma carteira no site ou usando o bot do Telegram. Em seguida, um bloco agent_auth resume os mesmos fatos de forma estruturada: tipo de identidade anônima, tipo de credencial api_key e um link para a documentação de registro.
A server card do MCP
Um descritor compacto do servidor MCP da TronSave: nome e versão, transporte (http-streamable) com endpoint e métodos, um bloco de capacidades que declara tools, resources e prompts (cada um com listChanged), os dois esquemas de autenticação suportados com o formato exato do cabeçalho e links para um guia rápido e para a documentação.
Declarar as capacidades que você não tem não é enchimento. Um agente que sabe que não há resources nem prompts para de procurá-los.
O manifesto de agent skills
A camada mais recente. O agent-skills/index.json segue o schema de descoberta do agentskills.io e anuncia uma skill, tronsave-api, do tipo skill-md: um documento Markdown que um agente pode carregar como instruções de trabalho:
{
"$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
"skills": [
{
"name": "tronsave-api",
"type": "skill-md",
"url": "https://tronsave.io/.well-known/agent-skills/tronsave-api/SKILL.md",
"digest": "sha256:bc8a8647...9141b"
}
]
}
Repare no digest. O manifesto traz um SHA-256 do arquivo da skill, para que um cliente possa verificar se baixou o que o site pretendia publicar. Skills são instruções que um agente vai executar, e isso faz valer a pena checar a integridade delas de um jeito que uma página de marketing nunca exige.
A regra que nenhum manifesto consegue impor
Todos os arquivos acima são um retrato de um momento. O serviço continua mudando.
Um exemplo concreto deste mesmo stack. Quando este artigo foi escrito pela primeira vez, em agosto de 2026, o manifesto de skills descrevia o servidor MCP com 27 ferramentas tipadas, enquanto o tools/list ao vivo retornava 29, e a server card listava GET entre os métodos de transporte, embora o GET estivesse desativado. Em 28 de outubro de 2026, o servidor (versão 1.2.0) retornava 53 ferramentas e a server card já tinha sido corrigida para POST e DELETE, mas o guia rápido em mcp.tronsave.io/quickstart ainda falava em 25 ferramentas. Em 7 de novembro de 2026, o servidor ao vivo informava a versão 1.5.1, ainda com 53 ferramentas, enquanto a server card continuava dizendo 1.2.0.
Nada disso é um bug no caminho do agente: é a defasagem normal entre um documento publicado e um serviço em execução. A lição vale para toda integração desse tipo: use os manifestos para descobrir e o servidor como fonte da verdade. Enumere as capacidades em tempo de execução com tools/list em vez de fixar no código um número que você leu em um arquivo, e deixe o handshake negociar a versão do protocolo em vez de impor uma.
O que um agente deve fazer com as credenciais
A descoberta termina na autenticação, e o modelo de sessão merece um parágrafo porque é a parte com consequências reais. Dados de mercado e cotações não exigem login: no servidor ao vivo (versão 1.5.1, verificado em 7 de novembro de 2026), 18 das 53 ferramentas são públicas, e cada ferramenta declara seu nível de acesso em _meta["io.tronsave/auth"]. Para todo o resto, o login gera um de dois tipos de sessão com alcances diferentes: uma sessão ApiKey fica restrita a operações da conta interna, enquanto uma sessão por assinatura é vinculada à carteira e necessária para as ferramentas de identidade do usuário e para a maioria das alterações na plataforma. Uma API key não ganha acesso de nível assinatura às escondidas; ela simplesmente falha nessas ferramentas.
O login é vinculado à conexão MCP, e o id da sessão trafega no cabeçalho do transporte, nunca nos argumentos das ferramentas. Trate-o como um segredo. Um id de sessão vazado permite que alguém aja com os direitos daquela sessão até ela expirar, e é exatamente por isso que a sessão ApiKey, mais restrita, é o padrão certo para trabalho autônomo.
Se você vai construir isso para o seu próprio site
O stack é pequeno o bastante para ficar pronto em uma tarde:
/llms.txt: um parágrafo de resumo e links selecionados com contexto. Mantenha-o curto./.well-known/api-catalog: uma âncora por API, cada uma com uma descrição para máquinas e uma documentação para pessoas./.well-known/oauth-protected-resource: publique-o quer sua API principal use OAuth, quer não.- Um documento de autenticação: nomes exatos dos cabeçalhos e sua grafia, e como uma pessoa obtém uma credencial.
- Uma server card do MCP, se você roda um servidor, declarando tanto as capacidades que faltam quanto as que você tem.
- Um manifesto de agent skills com digest, se você publica skills.
/.well-known/security.txt: com uma data de expiração que você vai mesmo renovar.
Depois, inclua uma coisa no seu processo de release: gere os manifestos de novo sempre que o serviço mudar. Os arquivos são baratos de publicar e fáceis de esquecer.
FAQ
O llms.txt é um padrão?
É mais uma convenção amplamente adotada do que um padrão do IETF. Os arquivos de /.well-known/ ao lado dele — api-catalog, metadados de recurso protegido, security.txt — são RFCs de verdade.
Publicar esses arquivos ajuda no SEO?
Não diretamente. Eles ajudam agentes e assistentes a usar seu serviço corretamente depois que chegam. Trate-os como documentação de integração em um endereço convencional, não como fator de ranqueamento.
Devo publicar um api-catalog se tenho só uma API?
Sim: o valor está na localização previsível, não no número de entradas. Uma âncora com uma descrição legível por máquinas basta.
Por que publicar metadados de recurso protegido sem OAuth?
Porque os clientes procuram por eles de qualquer forma. Responder com o identificador do recurso e a forma de envio das credenciais é mais útil do que um 404, mesmo quando a resposta para sua API principal é “usamos API keys, não OAuth”. A TronSave faz as duas coisas: metadados de API key no tronsave.io e um login OAuth completo para o endpoint MCP.
Como obtenho uma API key da TronSave?
Conecte uma carteira TRON no site e faça login, ou use a seção de informações do usuário do bot do Telegram. Não existe endpoint de registro programático para API keys, e o documento de autenticação diz isso abertamente em vez de deixar você descobrir sozinho. Apps MCP que se conectam pelo login OAuth pulam essa etapa: a página de login pede sua chave ou uma assinatura de carteira.
Por onde começo se só quero usar a API?
Os SDKs oficiais a encapsulam em cinco linguagens, e o guia de automação com a API cobre os endpoints diretos. Arquivos de descoberta são para agentes que precisam encontrar o caminho sozinhos.
Conclusão
Tornar um serviço legível para um agente de IA não é tanto uma disciplina nova, e sim uma antiga com um novo público: diga o que você é, liste o que expõe, seja exato sobre credenciais e admita o que não suporta. Os arquivos são convencionais e o esforço é pequeno. O que exige disciplina de verdade é mantê-los corretos, porque um agente vai acreditar no seu manifesto até o exato momento em que o servidor o contradisser.
Aponte um agente para ele: o endpoint MCP é https://mcp.tronsave.io/mcp (com um endpoint de testnet ao lado). Veja nosso guia do servidor MCP para o login e as famílias de ferramentas e depois acompanhe as cotações em relação ao mercado de energia ao vivo.
A TronSave publica este blog e os arquivos de descoberta descritos aqui. O conteúdo dos arquivos, o número de ferramentas e as versões do protocolo refletem o que estava publicado e o que o servidor ao vivo retornava no momento da escrita, e vão mudar: enumere em tempo de execução em vez de confiar nos números citados acima. Isto não é aconselhamento financeiro.


