Documentação do MCP

Como conectar

O servidor fica em https://htmly.com.br/api/mcp (transporte HTTP, JSON-RPC). Há dois jeitos de autenticar:

OAuth (recomendado)

Aponte o cliente para a URL do servidor, sem chave nenhuma: o navegador abre para você entrar na sua conta HTMLy e autorizar. Funciona no claude.ai (conector personalizado: cole a URL e aprove), no Claude Code, no Cursor, no Codex e no Gemini CLI.

O caminho mais curto é instalar o pacote público htmlybr/skills, que registra o servidor e ensina o agente a publicar. Como skill, para qualquer agente compatível:

npx skills add htmlybr/skills

Como plugin do Claude Code:

claude plugin marketplace add htmlybr/skills
claude plugin install htmly@htmlybr-skills

Como extensão do Gemini CLI:

gemini extensions install https://github.com/htmlybr/skills

Para agentes que descobrem servidores sozinhos, o HTMLy publica um MCP Server Card em /.well-known/mcp/server-card.json. Se preferir registrar o servidor na mão, no Claude Code:

claude mcp add --transport http htmly https://htmly.com.br/api/mcp

No Codex:

codex mcp add htmly --url https://htmly.com.br/api/mcp
codex mcp login htmly

API key

Para script, CI ou cliente sem navegador: a sua chave está na página de Perfil (/profile), enviada como Bearer token. É a mesma da API v1.

claude mcp add --transport http htmly https://htmly.com.br/api/mcp \
  --header "Authorization: Bearer SUA_API_KEY"

Conexões

Cada cliente autorizado por OAuth aparece no seu Perfil, no card Conexões com IA, com o nome do aplicativo, a data e a hora da autorização, o último uso (ou "nunca usado", que separa a conexão viva de uma reconexão antiga do mesmo cliente) e a data de expiração. Revogar corta o acesso na hora: o token de acesso e o de renovação morrem juntos, e a próxima chamada daquele cliente volta 401.

• O token de acesso vale 7 dias e é renovado em silêncio por até 90 dias. Depois disso o cliente pede uma nova autorização na tela do HTMLy.
• Regenerar a API key não mexe nas conexões OAuth, e revogar uma conexão não mexe na API key. São credenciais independentes: corte cada uma no lugar dela.
• Do lado da IA, remova o conector nas configurações dela para o cliente parar de tentar. A revogação no HTMLy já garante que nenhuma chamada passa.

As 4 tools

Fluxo típico de edição: get_site (lista os arquivos) → read_file (lê o que vai mudar) → publish_site (envia só o que mudou).

publish_site: merge seguro por padrão

Num site existente, o publish_site funciona por merge: arquivo enviado sobrescreve, arquivo não enviado fica no ar. Seu agente não consegue apagar páginas por acidente, nem quando trunca o bundle no meio da transcrição. Apagar é sempre um pedido explícito:

• delete_paths: lista de arquivos a remover, junto com um bundle ou sozinho. index.html não pode ser removido; path que não existe falha a chamada inteira (nada é aplicado).
• mode: "replace": reconstrói o site do zero com exatamente este bundle. Exige expected_file_count igual ao número de arquivos enviados; se não bater, nada muda. É a trava contra bundle truncado.
• is_indexable: false tira o site dos buscadores (meta noindex + header X-Robots-Tag em toda resposta, PDFs e assets incluídos). Ideal para preview. Omitido, mantém a configuração atual; site novo nasce indexável.

Na criação (slug novo), o bundle precisa conter index.html na raiz. Em update por merge, pode ser parcial: um arquivo que seja. Cada arquivo vai como content (texto UTF-8) ou content_base64 (binário), nunca os dois.

Os outros parâmetros

• slug: Endereço do site (3 a 63 caracteres, minúsculas, números e hífen). Omitido, o servidor gera um. Se for de um site seu, esse site é atualizado.
• title: Nome do projeto no painel (até 255 caracteres). Não aparece no site.
• meta_description: Descrição para buscadores (até 160 caracteres), injetada na homepage.
• use_bonus: Só depois de um erro de limite diário que avise bônus disponível: repete a publicação gastando o bônus único da conta. Nunca envie de antemão.

A resposta confere o trabalho

Toda publicação devolve o relatório do que aconteceu. Confira files_kept: são os arquivos que continuam no site sem terem vindo neste bundle. Se algo aparecer aí que deveria ter sido atualizado, o bundle chegou incompleto. Confira também storage_bytes contra a soma dos seus arquivos locais.

{
  "status": "published",
  "url": "https://meu-site.htmly.com.br",
  "slug": "meu-site",
  "storage_bytes": 578654,
  "files_written": [{ "path": "styles.css", "bytes": 4461 }],
  "files_deleted": [],
  "files_kept": ["index.html", "sobre/index.html", "assets/logo.webp"]
}

Para que o MCP serve (e para que não)

Cada arquivo viaja como texto dentro da chamada, então o canal é ideal para site gerado na conversa e edição pontual. Uma chamada comporta na prática algo em torno de 100KB de conteúdo; site maior se publica em lotes de chamadas merge. O segundo lote não apaga o primeiro.

• Publique cada página junto dos assets que ela referencia (ou os assets antes do HTML): asset referenciado antes de existir pode fixar um 404 no cache da CDN.
• Para migrar um site grande já pronto, o caminho melhor segue sendo o upload por ZIP no painel.
• Sites são estáticos: HTML, CSS, JS, imagens, fontes, PDF e mídia. Nada de backend; formulário só com action externo.

Limites e validações

• Extensões permitidas: html, css, js, json, xml, svg, png, jpg, jpeg, gif, webp, ico, woff, woff2, ttf, eot, otf, pdf, mp4, webm, ogg, mp3, wav, txt, csv. (.webmanifest fica fora: use manifest.json.)
• MIME real validado: o conteúdo do arquivo precisa corresponder à extensão. Um .js vazio, por exemplo, é rejeitado. HTML com tag PHP é bloqueado.
• Storage por site: conforme o plano (Free 10MB, Starter 50MB, Pro 500MB, Agency 2GB), calculado sobre o estado final do merge.
• Rate limit por plano: Free 30/min, Starter 45/min, Pro 60/min, Agency 120/min. O mesmo da API v1.
• Free: 3 atualizações de site por dia (criação não consome).
• Conteúdo escaneado: toda publicação passa pela varredura de abuso do HTMLy, como qualquer upload.

Erros comuns

As mensagens de erro são escritas para o agente se corrigir sozinho: dizem o que aconteceu e o próximo passo.