Claude Mods API: aggiungere comandi e tool personalizzati

La Claude Mods API permette di aggiungere un comando per l’utente o un tool che Claude può chiamare. Un comando è adatto a una consultazione esplicita; un tool serve quando quella funzione deve essere disponibile nel ragionamento dell’agente. La scelta dell’ingresso determina descrizione, input, gestione degli errori e autorità della funzione. Guida ufficiale Mods API.

Questa guida è verificata il 9 ottobre 2026 e usa un esempio progettato in sola lettura: consultare titolo e stato di un ticket fittizio. Non è un’integrazione cliente eseguita. Per la confezione del plugin segui il primo mod TypeScript; per scegliere fra meccanismi diversi parti dalla guida ai Mods di Claude.

Quando basta un comando e quando serve un tool?

Se una persona vuole aprire uno stato o consultare un dato preciso, un comando mantiene la scelta esplicita. L’utente decide quando eseguirlo e quale argomento passare. È una buona prima opzione per una funzione nuova, perché il suo uso è facilmente riconoscibile nel workflow. Non obbliga a rendere la funzione disponibile in ogni situazione del modello.

Un tool è più adatto quando Claude deve poter ottenere quel dato per completare un’attività. La sua descrizione deve quindi chiarire non soltanto cosa fa, ma quando è pertinente. «Gestisce ticket» è troppo largo per una consultazione che restituisce titolo e stato. «Legge titolo e stato di un ticket tramite identificativo, senza modificarlo» è un contratto più utile.

I due ingressi possono richiamare lo stesso nucleo di consultazione, ma non devono duplicarne le regole. L’autorizzazione appartiene a quel nucleo o al servizio affidabile che legge i dati. Se una regola vive soltanto nel testo della descrizione, una forma diversa di invocazione può non rispettarla. La guida agli agenti AI aiuta a riconoscere la differenza fra istruzione e capacità esposta.

Come progettare un lookup ticket prima di registrarlo?

Scrivi quattro condizioni: quale identificativo accetta, quale fonte consulta, quali campi restituisce e quale effetto esclude. Nel nostro esempio progettato il ticket è sintetico, la funzione è read-only e il risultato contiene titolo e stato. Non comprende allegati, conversazioni o anagrafiche. Un output piccolo è più semplice da verificare e non introduce dati senza una necessità.

Definisci poi tre esiti diversi. Successo significa che il record autorizzato è stato trovato. Non trovato significa che la consultazione ha funzionato ma quel record non c’è. Errore significa che la funzione non ha potuto verificare il dato. Restituire «nessun ticket» quando il servizio non risponde trasformerebbe un problema tecnico in un’informazione falsa.

Il primo test non ha bisogno di una rete aziendale. Puoi costruire fixture con un identificativo presente, uno assente e una risposta di errore. I nomi sintetici devono essere riconoscibili come esempi. Soltanto dopo aver verificato questo contratto conviene collegare il servizio reale, con accessi e policy adatti. La guida alle API AI offre il quadro del confine fra applicazioni.

Quale JSON Schema usare per un input piccolo?

Un esempio di schema applicativo progettato, non un handler completo, è:

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Identificativo del ticket sintetico da consultare"
    }
  },
  "required": ["id"],
  "additionalProperties": false
}

Questo contratto richiede una stringa e limita i campi previsti. Non certifica che l’identificativo sia autorizzato, esistente o privo di conseguenze nel servizio collegato. Una volta ricevuto l’input, la funzione deve controllare il valore secondo le regole del sistema. La sintassi JSON valida è il punto di partenza, non il completamento dell’integrazione.

Evita di inserire nell’input un campo che permette al modello di scegliere liberamente il livello di autorizzazione o l’organizzazione da impersonare. L’identità e il perimetro dell’accesso devono derivare da un contesto affidabile. Il modello può chiedere un dato; non deve poter trasformare un parametro in un privilegio. Anche una funzione in sola lettura può esporre informazioni riservate.

Registrazione e nomi canonici: cosa verificare?

La guida registra comandi e tool all’avvio della sessione. I comandi vengono gestiti su command.run; i tool su chiamate filtrate per il nome canonico. Un tool registrato da un plugin chiamato ufficio-demo, con nome ticket, viene identificato nella forma mcp__ufficio-demo__ticket. È un esempio di nomenclatura, non un server esterno creato da questa guida. Mods API: comandi e tool.

Il prefisso può generare confusione: un nome simile a quelli MCP non significa che il pacchetto sia un tutorial per costruire un server MCP. Il confine del mod resta quello di Claude Code. Se la funzione deve essere riutilizzata da più applicazioni, può essere opportuno esporla attraverso un servizio separato e lasciare al mod il ruolo di ingresso locale.

Per i comandi scegli un nome che non collide con quelli già presenti. La documentazione descrive errori di registrazione per nomi occupati. Una collisione va trattata come un errore riconoscibile: non deve far sembrare che il comando sia disponibile mentre manca. Prima di decidere il nome, controlla gli ingressi dell’ambiente reale e conserva un’identità stabile nel README.

Quando usare immediate e isDeferred?

immediate: true consente a un comando di essere eseguito mentre Claude lavora. Questo rende necessaria una domanda sullo stato: la funzione legge dati che potrebbero cambiare durante il turno? Se apri soltanto un pannello informativo il problema può essere limitato; se modifichi uno stato condiviso devi definire ordine e consistenza. Non aggiungere questa opzione per rendere ogni comando apparentemente più rapido.

Per i tool, isDeferred ha un confine di versione 2.1.293 o successiva. La release descrive la possibilità di esporre subito lo schema con isDeferred: false. Controlla il campo nei tipi locali prima di usarlo e annota il requisito per il team. Release ufficiale 2.1.293.

Non ricavare un vantaggio universale da una scelta di esposizione. Una funzione sempre disponibile può aiutare un task o introdurre un’opzione inutile. La decisione dipende dal bisogno, dalla descrizione e dalla frequenza d’uso. Il criterio di verifica è se Claude sceglie il tool nelle situazioni progettate, non una promessa generale di minore costo o migliore ragionamento.

Come rendere gli errori utili senza esporre troppo?

Il messaggio deve aiutare a decidere il prossimo passo. «Identificativo mancante» suggerisce di correggere l’input. «Dato non disponibile» suggerisce di verificare la fonte. «Accesso non consentito» richiede un responsabile o un percorso autorizzato. Evita un unico testo ambiguo per tutti gli errori, ma non riportare token, configurazioni segrete o dettagli interni non necessari.

Il risultato positivo dovrebbe essere altrettanto misurato. Nel lookup progettato basta indicare identificativo, titolo e stato, con il significato del dato e l’eventuale riferimento temporale utile. Non aggiungere una sintesi inventata delle conversazioni se la funzione non le legge. Se il record contiene testo esterno, consideralo un dato da trattare nel suo contesto, non una nuova istruzione al plugin.

Una verifica del risultato del lookup

Controlla che un ticket presente restituisca soltanto i campi previsti. Un identificativo assente deve essere distinto da un errore di rete. Un accesso negato non deve rivelare il contenuto del record. Una risposta malformata della fonte deve produrre un errore riconoscibile. Infine verifica che nessun caso trasformi la consultazione in una modifica.

La guida a testare un mod permette di progettare questi casi con stub. Prima di collegare dati aziendali leggi anche AI e sicurezza dei dati. «Read-only» descrive un effetto, non dimostra il rispetto di ogni permesso o la correttezza della destinazione.

Una consultazione deve usare cache o leggere sempre la fonte?

La risposta dipende dalla decisione che usa il dato. Un titolo può cambiare poco, mentre uno stato operativo può cambiare proprio durante il task. Se il progetto usa una cache, il risultato deve rendere comprensibile la freschezza del dato e il criterio di aggiornamento. Non inventare un campo API per risolvere la questione: definisci prima il contratto applicativo e verifica quali metodi della versione installata lo supportano.

Un esempio progettato può distinguere «stato letto ora», «ultima lettura disponibile» e «dato non verificato». Il modello deve poter interpretare la differenza senza trasformare una risposta vecchia in certezza. Il test include quindi una fixture cambiata e una fonte indisponibile. Se il requisito richiede un dato aggiornato, non restituire silenziosamente il vecchio valore come successo.

La stessa attenzione serve al comando utente. Una persona può richiamarlo due volte e aspettarsi una nuova consultazione; se il comportamento è diverso, la descrizione deve chiarirlo. Conservare un valore può essere utile, ma rende necessario decidere chi lo invalida e quando. Un mod con rete e stato non dovrebbe nascondere questa responsabilità dentro una scorciatoia. Per una prima versione, una lettura piccola con esiti espliciti può essere più facile da verificare di una cache introdotta senza un bisogno misurato.

Due scenari ipotetici: assistenza interna e team di sviluppo

Esempio ipotetico: una PMI di Vicenza consulta ticket tecnici interni. Il responsabile vuole che uno sviluppatore possa richiamare uno stato senza aprire un altro sistema. Inizia con un comando utente e fixture sintetiche. Il risultato non include nome del cliente né allegati, perché per decidere il prossimo passaggio bastano titolo tecnico e stato.

Dopo la prova il team valuta un tool per Claude, ma ne limita la promessa alla stessa consultazione. Non aggiunge chiusura ticket o modifica priorità nella prima versione. Se una richiesta richiede un’azione, il componente la lascia al workflow già autorizzato. Il contratto read-only resta piccolo e comprensibile anche per chi approva il plugin.

Esempio ipotetico: una software house di Bari collega il proprio tracker. Il tool deve aiutare Claude a controllare il requisito di un task prima della modifica. Il responsabile definisce quali progetti sono accessibili attraverso credenziali e servizio, senza delegare al parametro del tool la scelta dei privilegi. Le prove includono ticket assente, progetto non autorizzato e fonte temporaneamente indisponibile.

Il team non considera il risultato una specifica completa se il tracker contiene istruzioni ambigue. Il reviewer confronta il dato con il requisito del progetto e con il diff. Per distribuire la funzione conserva versione, schema e casi di test nella fonte del team, seguendo Mods e sicurezza organizzativa.

Quali errori trasformano una funzione piccola in un rischio?

Il primo è esporre un tool con descrizione più ampia delle sue capacità. Il secondo è usare lo schema come autorizzazione. Il terzo è confondere assenza del record con errore della fonte. Il quarto è filtrare il nome visibile invece del canonico. Il quinto è introdurre scritture dentro una funzione presentata come consultazione.

Un’altra trappola è presumere che la policy delle tool call protegga ogni chiamata diretta del mod. I Mods non sono sandboxati; i loro accessi a filesystem e processi hanno un confine da esaminare. Sicurezza dei plugin. La review deve confrontare il codice con la promessa, non accontentarsi del nome scelto per il tool.

Come applicare la Mods API a un’integrazione aziendale?

Parti da una consultazione precisa, con dati minimi e un proprietario della fonte. Definisci chi invoca la funzione, quale identità autorizza l’accesso e quali esiti sono possibili. Poi costruisci prove sintetiche e una procedura di distribuzione. La diagnosi dei Mods aiuta quando la funzione registrata non appare o il comportamento differisce tra macchine.

Se il tuo team deve portare una consultazione interna dentro Claude Code, il servizio di agenti AI può aiutare a scegliere il confine fra funzione locale e integrazione condivisa. Le guide alle API AI e a Claude Code completano la decisione prima di aggiungere capacità che l’agente non deve ancora usare.