Hooks e MCP: filtri e handler in Claude Code

Hooks e MCP in Claude Code possono collaborare in due modi distinti: un hook può intercettare una normale chiamata a un tool MCP, oppure usare un tool MCP come handler del controllo. Nel primo caso la chiamata esterna è l’oggetto da osservare; nel secondo il tool esegue la verifica. Confondere questi percorsi porta spesso a matcher e permessi sbagliati. Matching MCP e handler mcp_tool.

Per controllare una chiamata serve il suo nome canonico, non una label inventata dal team. Per richiamare un handler servono invece server, tool e input coerenti con la connessione effettiva. Autenticazione e disponibilità devono essere risolte prima di affidare al server una responsabilità. La guida ai Claude Code Hooks presenta il quadro; qui separiamo i due contratti.

Fonti verificate il 9 ottobre 2026. I nomi di server e tool negli esempi sono placeholder dichiarati; non descrivono integrazioni installate o test eseguiti. Gli scenari usano dati sintetici e non autorizzano operazioni automatiche su sistemi aziendali.

Che cosa controlla un hook su una chiamata MCP?

Una chiamata MCP attraversa eventi di tool come le altre operazioni supportate. Un PreToolUse può leggere la chiamata prima dell’esecuzione; un PostToolUse può reagire dopo un risultato riuscito. Il matcher seleziona il nome del tool. Lo script o l’handler deve poi interpretare l’input secondo lo schema di quella integrazione. MCP tools nella reference.

Per esempio, un team può voler richiedere attenzione prima di un tool capace di aggiornare un ticket. Questa non è la stessa policy di un tool che cerca documentazione. Il nome del server da solo non descrive la sensibilità delle operazioni: un’integrazione può offrire letture e scritture, con dati e permessi diversi.

Non restituire allow su tutto un server perché contiene uno strumento utile. Parti dal tool necessario e dai suoi argomenti. Se la policy riguarda scrittura su file o comandi, PreToolUse per proteggere file e comandi mostra la stessa logica preventiva in un contesto locale.

Come leggere i nomi canonici senza dedurli dalla UI?

La reference usa nomi nella forma mcp__server__tool per il matching. Il nome reale va osservato nella sessione e nella configurazione disponibile. Una schermata può mostrare un titolo leggibile che non coincide con la stringa confrontata dal matcher. Prima di scrivere una regex, registra il nome canonico del tool che vuoi includere. Match MCP tools.

Un pattern illustrativo ^mcp__demo_catalog__.*$ seleziona i tool del server denominato demo_catalog se quel nome corrisponde alla registrazione reale. È un placeholder, non un server esistente. Gli ancoraggi rendono esplicito che il confronto deve coprire il nome intero. Il matcher può essere interpretato come regex quando include metacaratteri, secondo le regole documentate.

Controlla anche un tool dal nome simile ma di un altro server. Una prova positiva dimostra che il filtro include il caso previsto; una prova negativa dimostra se il confine esclude ciò che volevi lasciare fuori. Per questo la precisione del nome è un requisito di funzionamento, non soltanto una scelta di stile.

Un esempio di intercettazione con un command hook

La registrazione seguente intercetta soltanto un nome sintetico e richiama uno script locale. demo_catalog e update_record sono placeholder: il progetto deve sostituirli con i nomi letti nella sua sessione. Lo snippet non è stato eseguito e non implica un’autorizzazione alla scrittura del record.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__demo_catalog__update_record",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/check_catalog_call.py\""
          }
        ]
      }
    ]
  }
}

Lo script riceve il JSON del hook e decide secondo PreToolUse. Deve conoscere lo schema di update_record: campi obbligatori, significato dell’operazione e condizioni consentite. Non può supporre che un campo chiamato “preview” renda il tool read-only se il server non lo garantisce.

Apri /hooks e verifica la registrazione, poi prova con input sintetici. Debug dei Hooks aiuta quando una chiamata visibile nella UI non produce l’esecuzione attesa. La diagnosi parte dal nome e dall’evento, prima della logica dello script.

Quando un tool MCP diventa l’handler?

Con type: "mcp_tool", Claude Code richiama uno strumento su un server configurato per eseguire il controllo. La reference richiede server e tool; input può fornire argomenti con sostituzione di valori dell’evento. L’output testuale del tool viene trattato secondo il percorso di output dei command hook. MCP tool hook fields.

La differenza pratica è chi fa il lavoro. Nel caso precedente uno script locale osserva un tool esterno. In questo caso il server esterno osserva i dati che gli passi per il controllo. Devi quindi decidere quali informazioni servono e dove vengono elaborate, oltre a verificarne disponibilità e autorizzazione.

Un handler non deve essere usato come scorciatoia per avviare un’integrazione mai configurata. Controlla la connessione fuori dal hook, con un’operazione consentita e dati sintetici. Se il server richiede login o autorizzazioni, risolvili prima di considerarlo un prerequisito del controllo. Un fallimento di autenticazione non è una valutazione negativa del codice.

Un handler read-only con input limitato

La seguente configurazione illustra un server ipotetico demo_checker che offre inspect_file. Questo tool dovrebbe leggere un file e restituire un risultato senza scriverlo; la garanzia deve essere implementata nel server e nei suoi privilegi. I nomi sono placeholder e la configurazione non è stata eseguita. Esempio mcp_tool ufficiale.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "mcp_tool",
            "server": "demo_checker",
            "tool": "inspect_file",
            "input": {
              "path": "${tool_input.file_path}"
            }
          }
        ]
      }
    ]
  }
}

Qui l’oggetto controllato è un file modificato con Edit o Write; l’handler che lo controlla è MCP. Non si tratta di intercettare una chiamata MCP fatta da Claude. Questa frase deve comparire nella documentazione del progetto, perché due configurazioni con termini simili possono avere un percorso dei dati molto diverso.

Un percorso passato al server non significa automaticamente che il server possa leggerlo. Se server e client girano in ambienti separati, il filesystem può essere differente. Il servizio deve sapere come interpretare quel riferimento; non copiare automaticamente il file verso una rete per risolvere l’errore.

Che cosa cambia per un server distribuito dentro un plugin?

La reference distingue il nome scoped di un server incluso in un plugin. Per il campo server di un handler, la forma documentata è plugin:<nome-plugin>:<nome-server>, invece della sola chiave del server. I nomi canonici delle chiamate e il riferimento del handler hanno responsabilità diverse, quindi non vanno scambiati senza verifica. Server MCP nei componenti plugin.

Un progetto che distribuisce la connessione attraverso un plugin deve conservare manifest, configurazione e istruzioni di autenticazione coerenti. La copia installata può avere una versione diversa da quella nel repository di sviluppo. Prima di diagnosticare un errore dello schema, verifica quale componente è realmente caricato.

Per il percorso di installazione consulta installare Mods e plugin in Claude Code. Per la decisione di packaging, Mods di Claude: cosa sono chiarisce il rapporto fra plugin, personalizzazione, Skills e MCP. Un server MCP può essere parte di un plugin senza diventare automaticamente un mod.

Quale confine rende un controllo realmente read-only?

Una regola sul testo della query non è una garanzia completa contro le scritture. SQL, procedure, tool composti e altri canali possono avere effetti che una regex non descrive. Se il requisito è accesso di sola lettura, anche l’account del database e i privilegi del servizio devono imporre quel limite.

La protezione si compone di questi livelli, senza attribuire a uno la responsabilità di tutti gli altri. Per il contesto informativo consulta AI e sicurezza dei dati. Il hook può rendere una policy visibile nel workflow; il servizio deve far rispettare il proprio contratto.

Che cosa verificare quando il server non risponde?

Se il server è scollegato, non autenticato o in errore, il controllo non ha prodotto la valutazione attesa. La diagnosi deve distinguere assenza del risultato e risultato negativo. Non dichiarare che “lo scanner ha trovato un problema” se lo scanner non è mai partito.

Le prove dovrebbero includere connessione valida, server indisponibile, tool inesistente e output malformato. Per ognuna osserva il comportamento dell’evento oltre al messaggio. Un controllo successivo con PostToolUse non annulla la modifica che lo ha provocato; lo ricorda la guida formatter e test dopo gli edit.

Una scheda di diagnosi senza dati riservati

Registra nome scoped del server, nome del tool, versione della configurazione e categoria di errore. Usa una fixture con percorso e contenuto fittizi. Non copiare token di autenticazione, transcript o risultati di clienti per mostrare che la connessione non funziona.

Se un servizio HTTP risolve meglio la disponibilità condivisa della policy, HTTP Hooks descrive un contratto differente. Non trasformare un errore MCP in un invio di dati a un endpoint alternativo senza una necessità definita.

Due integrazioni italiane con dati sintetici

Esempio ipotetico, non testato: una società di assistenza a Monza collega un catalogo di ticket di prova. Vuole che un tool di ricerca resti utilizzabile, mentre un aggiornamento richieda una decisione esplicita. Il team legge i nomi canonici, prepara matcher separati e prova chiamate incluse ed escluse. L’account del catalogo mantiene privilegi limitati; il hook non diventa una giustificazione per approvare tutte le operazioni del server.

Esempio ipotetico, non testato: un fornitore software di Cagliari possiede un controllo locale di file esposto tramite un server MCP. Dopo gli edit di Claude Code vuole ricevere il risultato dello scanner. Verifica prima il tool direttamente con un file sintetico, poi la sostituzione del percorso nel handler. Prova anche un percorso non leggibile e una risposta errata, senza chiamarli “codice non sicuro”: sono fallimenti del processo di controllo.

I casi usano due forme diverse di collaborazione. Il primo intercetta le chiamate del catalogo; il secondo chiama lo scanner come handler. Tenerle distinte rende più semplice scegliere permessi, input e test pertinenti.

Come evitare ricorsione e auto-approvazioni ampie?

Un controllo che richiama strumenti o agenti può generare altro lavoro osservato dal workflow. Il progetto deve identificare dove si attivano altri hook e impedire catene non intenzionali. Anche quando non si presenta una ricorsione tecnica, un controllo generico può produrre richieste duplicate e risultati poco attribuibili.

Hooks per subagent e team aggiunge la distinzione fra ruolo, fine task e fine risposta. Stop hook senza loop descrive la gestione delle continuazioni. La sicurezza della catena deriva da limiti e contratti leggibili, non dal fatto che tutti i componenti siano chiamati “controlli”.

Gli errori da evitare sono matcher basati sulla label, server scoped sbagliato, autenticazione non risolta, output ignorato e approvazione di un intero server per comodità. Mantieni il controllo dedicato a un’operazione o a una classe dichiarata, con una prova negativa ogni volta che allarghi il filtro.

Che cosa fare quando cambia il nome di un tool?

Un aggiornamento del server può cambiare nomi o schema degli argomenti. Il matcher precedente potrebbe non intercettare più la chiamata, mentre la registrazione continua a essere presente. Anche l’input del handler potrebbe riferirsi a un campo non più disponibile. Per questo la prova di compatibilità deve usare i nomi della versione effettivamente collegata.

Non sostituire il filtro preciso con un pattern generico soltanto per far ripartire il controllo. Verifica il nuovo nome, rivedi il contratto e ripeti un caso escluso. La manutenzione dell’integrazione include sia la connessione sia il confine della policy. Un aggiornamento riuscito del server non certifica automaticamente le configurazioni che dipendono dai suoi strumenti.

Come adottare il controllo in un progetto aziendale?

Documenta operazione osservata, handler eseguito, dati ricevuti e risultato atteso. La documentazione deve permettere a un collega di ricostruire il percorso senza accedere a informazioni riservate. Conserva fixture sintetiche e versioni dei componenti, poi ripeti le prove quando cambiano nomi o schema del server.

Per un’integrazione fra assistente e sistemi interni, la progettazione di agenti AI può partire dall’operazione minima e dai privilegi necessari. Il risultato utile è un controllo che vede esattamente il tool scelto, riceve solo i dati necessari e distingue una decisione valida da un servizio non disponibile.