API e servidor MCP do Citevana

API REST

Todas as respostas são JSON. Respostas bem-sucedidas trazem "ok": true. As ferramentas gratuitas retornam um resumo em linguagem simples e uma lista de tarefas ordenada por importância, com estimativas de tempo.

Exemplo de requisição

curl -s https://citevana.com/api/v1/tools/ai-crawlers \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

curl -s https://citevana.com/api/v1/sites \
  -H "Authorization: Bearer $CITEVANA_API_KEY"

Erros

Todos os erros usam o mesmo formato JSON, mostrado abaixo. Os códigos incluem invalid_request, invalid_url, blocked_host, fetch_failed, unauthorized, insufficient_scope, not_found, rate_limited e quota_exceeded.

{
  "ok": false,
  "error": {
    "code": "quota_exceeded",
    "message": "Daily api_calls quota reached."
  },
  "requestId": "req_…"
}

Limites e cabeçalhos

Toda resposta medida inclui X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (segundos Unix), descrevendo o limite em que a chamada foi contada. Uma resposta 429 também inclui Retry-After. Chamadas sem chave contam no limite compartilhado das ferramentas gratuitas da sua conexão de internet; chamadas com chave contam na cota diária api_calls do seu espaço de trabalho, e cada chave pode ter um limite diário menor. Uma chamada que não devolve resultado, porque o site não pôde ser acessado ou porque a proteção antibots respondeu no lugar dele, não é contada.

Navegadores podem chamar as ferramentas gratuitas de qualquer site sem chave. Endpoints que exigem chave não aceitam requisições de navegador entre origens; chame-os do seu servidor.

Adicione ?locale=es, pt-BR, de, fr, ja, id, hi, tr, vi ou ar a um endpoint de ferramenta para receber o resumo nesse idioma.

Fonte, verificada em 16 de setembro de 2026: https://spec.openapis.org/oas/v3.1.1.html

Servidor MCP

Conecte qualquer cliente MCP que aceite servidores remotos a https://citevana.com/api/mcp. Ele usa o transporte Streamable HTTP, responde em JSON e não mantém sessões.

• check_ai_crawlers — Quais rastreadores de IA de busca, assistentes e treinamento um site permite. Grátis.
• audit_page — Auditoria de SEO on-page e prontidão para IA de uma URL. Grátis.
• generate_llms_txt — Cria um arquivo llms.txt a partir do nome do site, um resumo e links. Grátis; nada é baixado.
• get_site_audit_summary — Última auditoria de um dos seus sites. Exige uma chave de API com read:audits.

O servidor aceita a revisão 2026-07-28 do protocolo (metadados por requisição e server/discover). Também aceita o handshake initialize das revisões 2025-11-25, 2025-06-18 e 2025-03-26.

As três ferramentas gratuitas funcionam sem autenticação e compartilham o limite sem chave de 3 verificações por dia por conexão de internet. Para get_site_audit_summary, seu cliente precisa enviar sua chave de API em um cabeçalho Authorization: Bearer, que também amplia esse limite diário. O Citevana ainda não oferece login OAuth para MCP.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "check_ai_crawlers",
    "arguments": {
      "url": "https://example.com"
    },
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

Fonte, verificada em 16 de setembro de 2026: https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http

Outros clientes MCP e seus próprios agentes

Se o seu cliente permite definir cabeçalhos HTTP para um servidor remoto, adicione Authorization: Bearer seguido da sua chave para liberar get_site_audit_summary. Uma chamada com chave conta na mesma cota diária api_calls da API REST; sem chave, ela conta no limite compartilhado das ferramentas gratuitas.

Extensão para Chrome

A extensão do Citevana para Chrome executa, por meio desta API, a verificação de rastreadores de IA e a auditoria da aba que você está vendo. Não exige conta e usa o limite sem chave; uma chave opcional amplia esse limite e mostra as auditorias dos seus sites. Ela está sendo preparada para a Chrome Web Store.

Ela pede só as permissões activeTab e storage, além de acesso à API do Citevana. Envia o endereço da página apenas quando você clica em uma verificação e nunca envia a query string.

Fonte, verificada em 16 de setembro de 2026: https://developer.chrome.com/docs/extensions/develop/concepts/activeTab

Segurança e privacidade

• Todas as ferramentas são somente leitura. Nada é alterado no seu site.
• Texto copiado das páginas baixadas é marcado como dado não confiável, para que assistentes de IA nunca sigam instruções contidas nele.
• Baixamos apenas páginas públicas, como CitevanaBot, e bloqueamos endereços de redes privadas e reservadas.
• Guardamos apenas um hash SHA-256 de cada chave de API. A chave é exibida uma vez e pode ser revogada a qualquer momento. A criação e a revogação de chaves ficam no log de auditoria.

CitevanaBot

Perguntas frequentes

Fontes

• https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http
• https://modelcontextprotocol.io/specification/2026-07-28/basic/versioning
• https://developers.openai.com/apps-sdk/deploy/connect-chatgpt
• https://developers.openai.com/apps-sdk/build/auth
• https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp
• https://spec.openapis.org/oas/v3.1.1.html
• https://developer.chrome.com/docs/extensions/develop/concepts/activeTab
• https://developer.chrome.com/docs/webstore/program-policies/policies