O Bot Protection tem um servidor MCP: seu assistente de IA pode ler as visões do seu painel e responder "por que esta requisição foi bloqueada?", "o que atacou /login ontem?" ou "quais IAs leram meu site esta semana?". Ele lê os mesmos dados que o painel mostra, só da sua conta. É somente leitura: não muda nenhuma configuração, não chama /v1/decide e não envia nada para lugar nenhum.
Crie uma chave MCP
Na página Configuração do painel, em Chaves MCP, escolha Criar uma chave MCP. Ela começa com kz_mk_ e aparece uma única vez: copie-a para a configuração do seu assistente. Quem pode criar uma chave de API pode criar uma. Uma chave MCP não é uma chave de API: ela funciona só no servidor MCP, e uma chave de API é recusada lá. Mantenha-a fora de qualquer repositório, como qualquer segredo.
O servidor fica em https://korzen.dev/bot-protection/mcp, por Streamable HTTP. Cada cliente envia a chave no header Authorization: Bearer.
Conecte seu assistente
Claude Code
claude mcp add --transport http korzen https://korzen.dev/bot-protection/mcp \ --header "Authorization: Bearer $KORZEN_MCP_KEY"
Claude Desktop
Em claude_desktop_config.json (Settings, Developer, Edit config), pelo mcp-remote, que repassa o header:
{
"mcpServers": {
"korzen": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://korzen.dev/bot-protection/mcp", "--header", "Authorization:${KORZEN_MCP_HEADER}"],
"env": { "KORZEN_MCP_HEADER": "Bearer kz_mk_..." }
}
}
}
Codex
Em ~/.codex/config.toml, com a chave na variável de ambiente KORZEN_MCP_KEY:
[mcp_servers.korzen] url = "https://korzen.dev/bot-protection/mcp" bearer_token_env_var = "KORZEN_MCP_KEY"
Cursor
Em ~/.cursor/mcp.json, ou em .cursor/mcp.json de um projeto:
{
"mcpServers": {
"korzen": {
"url": "https://korzen.dev/bot-protection/mcp",
"headers": { "Authorization": "Bearer ${env:KORZEN_MCP_KEY}" }
}
}
}
Os conectores web do Claude e do ChatGPT pedem login com OAuth, que o servidor ainda não oferece: use um cliente que aceite um header, como acima.
As ferramentas
| Ferramenta | O que ela lê |
|---|---|
get_decision | uma decisão, pelo request_id que /v1/decide respondeu: sua classe, bot score, tipos de evidência, país, rede e crawler, como a página Decisões mostra, com os seus limiares |
list_decisions | as linhas da página Decisões, com seus filtros: find (um request ID, um IP ou um User-Agent), path, class, country, asn, crawler, evidence, ua, since, older, e até 50 linhas por limit |
attacks | os ataques da visão geral, com as decisões e os bots da janela; since é 24h, 7d ou 30d |
ai_traffic | a página de tráfego de IA: quais crawlers e assistentes de IA leem seu site, com que frequência e quais páginas; since como acima |
Cada resposta é JSON. O que seus visitantes escreveram, um caminho ou a família de um User-Agent, vem em visitor_supplied, com caracteres de controle, bidirecionais e de largura zero escritos como escapes \u{...}: um visitante pode pôr num User-Agent palavras dirigidas ao seu assistente, e o servidor as entrega como dados, nunca como instrução. Mantenha ligada a aprovação de chamadas de ferramentas no seu cliente.
O que o servidor nunca faz
- Nunca muda nada: nenhuma configuração, regra, chave ou plano.
- Nunca lê dados de outra conta: uma chave lê só a sua própria conta.
- Nunca chama
/v1/decide, envia um evento ou conta como decisão: é grátis. - Nunca envia seus dados a terceiros, e nunca registra sua chave nem o que uma ferramenta respondeu: a linha de log de cada chamada guarda a ferramenta, os nomes dos argumentos e o tamanho da resposta.
- Nunca mostra mais do que o painel, nem como a detecção decide.
Limites
Cada chave MCP faz até 60 chamadas por minuto e 2.000 por dia; além disso o servidor responde 429 com os headers RateLimit e Retry-After. Uma chamada responde em até 5 segundos, ou diz que demorou demais. Uma conta guarda até 25 chaves MCP.
Revogue uma chave
Na página Configuração, cada chave MCP mostra quando foi criada e quando foi usada pela última vez, até o minuto. Revogar a desliga na hora: a próxima chamada do assistente é recusada com 401. Suas chaves de API e as chamadas do seu servidor não são afetadas.