Da MCP Server a CLI Agentici: Come Ho Tagliato il 90% dei Token

Uso MCP server da mesi. Li ho costruiti per Todoist, Polar, RunPod — ogni servizio che dovevo collegare a Claude passava da lì. Funzionavano, niente da dire.

Poi ho iniziato a guardare i numeri.

Una todoist tasks via MCP? Circa 2.800 token tra handshake, schema, richiesta e risposta. Per farmi vedere 5 task. Lo stesso risultato da CLI? 280 token. Un decimo.

Ho migrato 3 server in una settimana. I risultati sono stati talmente netti che non ho più toccato quei MCP.

---

Perché MCP consuma così tanto

Il Model Context Protocol fa bene il suo lavoro — è generico, robusto, gestisce stato e negoziazione. Il problema è che per operazioni tipo "mostrami i task di oggi" quel overhead non ha senso.

Ogni interazione MCP porta con sé:

• Handshake e capabilities
• Lo schema completo di ogni tool (parametri, tipi, descrizioni)
• JSON-RPC con tutto il suo overhead di protocollo
• Gestione dello stato persistente lato client

Per un CRUD, è come usare un TIR per consegnare una busta.

---

L'idea: un CLI che si racconta da solo

La svolta è stata semplice. Invece di un server che aspetta connessioni, un comando che fa il suo lavoro e basta. Con un trick: un flag --ai che restituisce lo schema in JSON, così l'agente sa cosa può fare senza dover negoziare nulla.

todoist --ai brief
# portfolio v1.0.0 - AI-native Todoist CLI...
# Commands:
#   tasks            List tasks (today + overdue by default)
#   task create      Create a new task...

todoist tasks
# - [8765432100] Fix login bug (due: 2026-04-07, p3, project: Building)

Claude legge il brief (~200 token), esegue il comando (~100 token di output), fine.

300 token totali contro 3.000.

---

Come funziona in pratica

L'--ai viene intercettato prima ancora che Commander.js parsi i comandi. Niente auth, niente config — è solo documentazione:

const aiIndex = process.argv.indexOf('--ai')
if (aiIndex !== -1) {
  const sub = process.argv[aiIndex + 1]
  printAiManifest(sub)
  process.exit(0)
}

Il pezzo che fa la differenza è il when_to_use nel manifest. Non lascio che l'agente indovini quando usare un comando — glielo dico io:

{
  name: 'tasks',
  description: 'List tasks. Default: today + overdue.',
  when_to_use: 'When you need to see what tasks are due today,
                check overdue items, or list tasks for a project.',
  options: [
    { flag: '--project', type: 'string', description: 'Project name' },
    { flag: '--all', type: 'boolean', description: 'Show all active tasks' },
  ],
  examples: [
    { description: 'Today tasks', command: 'todoist tasks' },
  ],
}

L'output è plain text ottimizzato per essere letto sia da me che da Claude:

# Tasks - today + overdue
- [8765432100] Fix login bug (due: 2026-04-07, p3, project: Building)
- [8765432101] Deploy v2 (due: 2026-04-07, p4, project: Building)

Niente JSON wrapper, niente metadata aggiuntivi. Solo l'informazione.

---

I numeri

Li ho misurati su sessioni reali, non su benchmark sintetici:

Operazione	MCP (token)	CLI (token)	Risparmio
List tasks (Todoist)	~2.800	~280	90%
Revenue summary (Polar)	~2.200	~250	89%
Pod status (RunPod)	~3.100	~310	90%
Create task	~1.800	~180	90%

In una giornata tipo faccio 50-80 chiamate tool. Fanno 100-180K token risparmiati al giorno. In un mese il conto è significativo.

---

Quando NON usare un CLI

Non ho buttato via tutti gli MCP. Per alcune cose il server resta la scelta giusta:

• Streaming e real-time — il CLI non mantiene connessione
• UI embedded ricche — tipo il mio server fal.ai che ha React views dentro il protocollo MCP
• OAuth e setup complessi — dove serve gestire il lifecycle della connessione

La regola che uso: se l'operazione è "verbo + nome" (lista task, crea nota, mostra revenue), CLI. Se è un flusso continuo o servono UI custom, MCP.

---

Lo stack

Dopo 3 migrazioni ho standardizzato su:

• Bun come runtime — startup 10x più veloce di Node, bundler integrato
• Commander.js — standard de facto, niente di esotico
• --ai flag pre-parse — prima di tutto, prima dell'auth
• bun build --compile — per chi vuole il binary standalone

Un nuovo CLI lo metto in piedi in un paio d'ore partendo dal template. La parte più lunga è scrivere i when_to_use decenti.

---

Quello che ho migrato

• Todoist CLI — il primo, quello che mi ha convinto
• Polar CLI — revenue tracking, uso tutti i giorni
• RunPod CLI — gestione GPU cloud
• Portfolio CLI — quest'ultimo l'ho costruito per gestire questo stesso sito da terminale. Non è pubblico perché è troppo specifico per il mio setup, ma il pattern è lo stesso

---

Come replicare

Se hai un MCP server che fa CRUD:

1. Ogni tool MCP diventa un comando CLI
2. Scrivi un AI manifest con when_to_use per ogni comando
3. L'--ai flag va parsato prima di Commander, prima dell'auth
4. Output plain text di default, --json per quando serve strutturato
5. Opzionale: crea una skill Claude Code (un .md in ~/.claude/skills/) che dice a Claude quando e come usare il tuo CLI

Il risultato è un tool che funziona anche senza AI, costa un decimo con AI, e l'agente sa esattamente cosa farne.

Non tutti i server MCP vanno migrati. Ma quelli che fanno solo CRUD? Vale la pena provarci. I numeri parlano da soli.