Se il tuo agente ha una shell, dagli una riga di comando

Il Model Context Protocol è, con le sue parole, “an open-source standard for connecting AI applications to external systems”, uno standard open source per collegare le applicazioni AI a sistemi esterni (modelcontextprotocol.io). Il progetto lo paragona a una porta USB-C: una spina per molti dispositivi.

La specifica attuale, versione 2026-07-28, definisce host (l'applicazione AI), client (i connettori al suo interno) e server (i servizi che forniscono dati e strumenti), che comunicano in JSON-RPC. Un server può offrire risorse, prompt e strumenti. Gli strumenti sono ciò che gli agenti usano di più: il client chiede al server il loro elenco con tools/list, e ogni strumento ha un nome, una descrizione e uno JSON Schema per il suo input.

Una riga di comando non è automaticamente adatta agli agenti. Servono alcune proprietà che le persone chiedono di rado:

• Si descrive come dati: --help e un catalogo completo dei comandi in JSON, così l'agente non deve mai indovinare i flag.
• L'output è un contratto: con --json, esattamente un documento JSON su stdout, errori come JSON su stderr.
• I codici di uscita hanno un significato: correggere la chiamata, chiedere alla persona, attendere, riprovare. Un numero dice all'agente cosa fare dopo.
• Non aspetta mai un input che l'agente non può dare: senza terminale, nessuna domanda. I passaggi distruttivi richiedono un flag esplicito come --yes.
• Può mostrare invece di agire: --dry-run stampa la richiesta esatta senza inviarla.
• I segreti restano fuori dall'output, anche con --verbose e --dry-run, perché tutto ciò che l'agente vede finisce nel suo contesto.
• Si installa facilmente ovunque giri un agente, idealmente senza un albero di dipendenze.

Il team di ingegneria di Anthropic ha descritto il problema a novembre 2025: “Most MCP clients load all tool definitions upfront directly into context”, la maggior parte dei client MCP carica subito tutte le definizioni degli strumenti nel contesto, e quelle descrizioni aumentano tempi di risposta e costi (Code execution with MCP). La loro raccomandazione è lasciare che il modello legga le definizioni degli strumenti su richiesta.

Per correttezza, i client stanno recuperando. Claude Code ora rinvia per impostazione predefinita gli strumenti MCP: all'inizio della sessione si caricano solo i nomi degli strumenti e le istruzioni dei server, e la definizione completa arriva quando Claude cerca lo strumento (MCP tool search). Altri client possono ancora caricare tutto.

Una CLI ha il caricamento su richiesta gratis, perché nulla è nel contesto finché l'agente non esegue un comando. Abbiamo misurato quanto c'è da caricare in tm 0.3.0: il catalogo completo (tm schema --json) è di 377.203 caratteri, la panoramica di tutti i gruppi di comandi (tm --json) di 32.110, il gruppo delle fatture di 104.009. Un singolo comando ha una mediana di 934 caratteri su 157 comandi. Metodo: npx -y @time-momentum/cli@0.3.0 schema --json | wc -c e lo stesso per le altre chiamate, il 10 ott 2026.

Il catalogo non è piccolo. È proprio questo il punto: l'agente decide cosa caricare, di solito un gruppo o un comando.

Con MCP, “every intermediate result must pass through the model”, ogni risultato intermedio deve passare dal modello, come dice lo stesso articolo di Anthropic. Un elenco di 500 fatture che l'agente deve solo contare finisce comunque nel suo contesto.

In una shell, l'agente filtra prima di leggere. tm payments outstanding --json | jq '[.data[].summary.outstanding_micros] | add / 1000000' restituisce un numero: il totale aperto in euro. tm invoices list --all --json | jq '[.data[] | select(.status == "draft")] | length' conta le bozze su tutte le pagine. Le stesse righe funzionano in un cron job o in uno script di shell, senza alcun agente.

In MCP l'autorizzazione è facoltativa. I server remoti via HTTP dovrebbero seguire il flusso OAuth 2.1 della specifica; i server locali via stdio prendono le credenziali dall'ambiente. Per un'app di chat in cui ogni utente accede con il proprio account, OAuth è l'opzione più comoda.

Una CLI di solito lavora con una chiave API. È semplice, ma richiede attenzione: la chiave non deve mai comparire in ciò che l'agente legge. tm la tiene in un file locale con permessi 600 o in una variabile d'ambiente, scambia una chiave di scrittura con un token valido un'ora e non stampa mai la chiave, nemmeno con --verbose o --dry-run. Un token ottenuto da quello scambio non può creare nuove chiavi né eliminare l'account.

Ogni chiamata che un agente fa tramite una CLI è una riga che puoi copiare, leggere ed eseguire tu stesso. --dry-run va un passo oltre e mostra metodo, URL e corpo senza inviare nulla. Così il lavoro dell'agente si può verificare prima che accada, cosa che conta soprattutto per le fatture.

Anche MCP ha strumenti per questo, come l'MCP Inspector per sviluppatori. Ma una chiamata a uno strumento non è qualcosa che digiti nel tuo terminale per vedere cosa succede.

Una CLI è un pacchetto con una versione. Puoi bloccarla (npx -y @time-momentum/cli@0.3.0), tornare indietro (tm update --to <version>) e sapere che uno script che funzionava ieri funziona oggi. Quando l'API cambia in un modo che una vecchia versione sbaglierebbe, il server rifiuta quella versione con un errore chiaro e il comando di aggiornamento.

MCP versiona il protocollo per data e permette ai server di annunciare a runtime le modifiche al loro elenco di strumenti. Un server remoto decide da sé quali strumenti ottieni oggi. È comodo finché non si rompe nulla.

Claude Code, Codex, Cursor e la maggior parte degli agenti di coding possono eseguire comandi da shell. Una CLI funziona in tutti senza che il client debba supportare altro, anche in sandbox e CI.

• Client senza shell. claude.ai, Claude Desktop e le app mobili di Claude raggiungono gli strumenti esterni tramite connettori, che sono server MCP (documentazione Claude). Lì una CLI non può aiutare.
• Scoperta standard. Ogni server MCP risponde a tools/list allo stesso modo, e il registro MCP ufficiale elenca i server. Ogni CLI si documenta a modo suo.
• Accesso per utente. OAuth permette a ogni persona di collegare il proprio account senza gestire una chiave.
• Utenti non tecnici. Aggiungere un connettore in un'app di chat è più facile che installare una riga di comando.

Gli agenti dei nostri utenti lavorano già in una shell, sui progetti dei clienti. Per questo Time Momentum non ha un server MCP. Ha tm, una riga di comando che gestisce l'intero prodotto: impegno, clienti, commesse, progetti, fatture e fatture elettroniche, pagamenti, report delle attività e redditività.

tm non ha dipendenze a runtime. Ogni operazione della REST API pensata per la riga di comando ha esattamente un comando, 143 operazioni nella versione 0.3.0, e un test lo impone a ogni modifica dell'API. tm skill restituisce la guida d'uso allineata alla versione installata. In Claude Code, tm skill --install aggiunge una breve skill che vi rimanda, e Time Momentum è disponibile anche come plugin per Claude Code.

Emettere o stornare una fattura ed eliminare richiedono un --yes esplicito. Senza terminale, altrimenti tm si ferma.