Il tuo assistente IA (MCP) · Documentazione di Bot Protection

Chiedi a Claude, Codex o Cursor perché una richiesta è stata bloccata o cosa ha attaccato il tuo sito: un server MCP in sola lettura legge le viste della tua dashboard con una chiave MCP.

Bot Protection ha un server MCP: il tuo assistente IA può leggere le viste della tua dashboard e rispondere a "perché questa richiesta è stata bloccata?", "cosa ha attaccato /login ieri?" o "quali IA hanno letto il mio sito questa settimana?". Legge gli stessi dati che ti mostra la dashboard, solo del tuo account. È in sola lettura: non cambia alcuna impostazione, non chiama /v1/decide e non invia nulla da nessuna parte.

Crea una chiave MCP

Nella pagina Configurazione della dashboard, sotto Chiavi MCP, scegli Crea una chiave MCP. Inizia con kz_mk_ e si vede una sola volta: copiala nella configurazione del tuo assistente. Chi può creare una chiave API può crearne una. Una chiave MCP non è una chiave API: funziona solo sul server MCP, e lì una chiave API viene rifiutata. Tienila fuori da qualsiasi repository, come ogni segreto.

Il server è su https://korzen.dev/bot-protection/mcp, tramite Streamable HTTP. Ogni client invia la chiave nell'header Authorization: Bearer.

Collega il tuo assistente

Claude Code

claude mcp add --transport http korzen https://korzen.dev/bot-protection/mcp \
  --header "Authorization: Bearer $KORZEN_MCP_KEY"

Claude Desktop

In claude_desktop_config.json (Settings, Developer, Edit config), tramite mcp-remote, che passa l'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

In ~/.codex/config.toml, con la chiave nella variabile d'ambiente KORZEN_MCP_KEY:

[mcp_servers.korzen]
url = "https://korzen.dev/bot-protection/mcp"
bearer_token_env_var = "KORZEN_MCP_KEY"

Cursor

In ~/.cursor/mcp.json, o in .cursor/mcp.json di un progetto:

{
  "mcpServers": {
    "korzen": {
      "url": "https://korzen.dev/bot-protection/mcp",
      "headers": { "Authorization": "Bearer ${env:KORZEN_MCP_KEY}" }
    }
  }
}

I connettori web di Claude e di ChatGPT chiedono un accesso con OAuth, che il server non offre ancora: usa un client che accetti un header, come sopra.

Gli strumenti

Strumento	Cosa legge
`get_decision`	una decisione, tramite il `request_id` che ha risposto `/v1/decide`: classe, bot score, tipi di prova, paese, rete e crawler, come li mostra la pagina Decisioni, con le tue soglie
`list_decisions`	le righe della pagina Decisioni, con i suoi filtri: `find` (un request ID, un IP o uno User-Agent), `path`, `class`, `country`, `asn`, `crawler`, `evidence`, `ua`, `since`, `older`, e fino a 50 righe con `limit`
`attacks`	gli attacchi della panoramica, con le decisioni e i bot del periodo; `since` è `24h`, `7d` o `30d`
`ai_traffic`	la pagina Traffico IA: quali crawler e assistenti IA leggono il tuo sito, quanto spesso e quali pagine; `since` come sopra

Ogni risposta è JSON. Ciò che hanno scritto i tuoi visitatori, un percorso o la famiglia di uno User-Agent, sta sotto visitor_supplied, con i caratteri di controllo, bidirezionali e a larghezza zero scritti come escape \u{...}: un visitatore può mettere in uno User-Agent parole rivolte al tuo assistente, e il server le consegna come dati, mai come istruzione. Tieni attiva nel tuo client l'approvazione delle chiamate agli strumenti.

Cosa il server non fa mai

Non cambia mai nulla: nessuna impostazione, regola, chiave o piano.
Non legge mai i dati di un altro account: una chiave legge solo il proprio account.
Non chiama mai /v1/decide, non invia eventi e non conta come decisione: è gratuito.
Non invia mai i tuoi dati a terzi, e non registra mai la tua chiave né cosa ha risposto uno strumento: la riga di log di ogni chiamata tiene lo strumento, i nomi dei suoi argomenti e la dimensione della risposta.
Non mostra mai più della dashboard, né come decide il rilevamento.

Limiti

Ogni chiave MCP fa fino a 60 chiamate al minuto e 2.000 al giorno; oltre, il server risponde 429 con gli header RateLimit e Retry-After. Una chiamata risponde entro 5 secondi, o dice di aver impiegato troppo. Un account ha fino a 25 chiavi MCP.

Revoca una chiave

Nella pagina Configurazione, ogni chiave MCP mostra quando è stata creata e quando è stata usata l'ultima volta, al minuto. Revoca la ferma subito: la chiamata successiva dell'assistente è rifiutata con 401. Le tue chiavi API e le chiamate del tuo server non cambiano.