Ridurre il consumo di token di MCP: come abbiamo tagliato del 60% le definizioni dei nostri strumenti

Il 27 ottobre, un utente pagante ha disdetto l'abbonamento ad AgentsRoom e ha indicato i token come motivo. Prima di discuterne, abbiamo misurato cosa aggiunge la nostra app a ogni agente che lancia.

Il numero più grande non era dove ce lo aspettavamo. Le nostre istruzioni di avvio erano piccole. Gli strumenti MCP che diamo a ogni agente (backlog, memoria di progetto, posta tra agenti, terminali, SSH, database e il resto) erano 191 strumenti e circa 380 KB di JSON. A circa 4 byte per token, fanno circa 95.000 token di definizioni degli strumenti. Una settimana prima erano 78.000. Nessuno l'aveva deciso: ogni nuovo strumento aveva semplicemente aggiunto il suo paragrafo.

Sviluppiamo AgentsRoom, un'app desktop che fa girare Claude Code, Codex e altri CLI di codice fianco a fianco e dà loro questi strumenti. Ecco cosa abbiamo misurato, cosa abbiamo tagliato senza togliere un solo strumento e il controllo che impedisce al problema di tornare. Puoi applicare tutto questo ai tuoi server MCP.

La risposta breve

• La definizione di uno strumento è JSON che il modello può leggere a ogni richiesta: nome, descrizione, schema di input. Conta circa 4 byte per token.
• Se la paghi a ogni turno o no dipende dal CLI. Claude Code rimanda gli strumenti MCP per impostazione predefinita e carica una definizione quando gli serve. Alcuni CLI inviano tutti gli schemi a ogni richiesta.
• Misura prima di tagliare. /context in Claude Code, oppure uno script di 40 righe che chiede a qualsiasi server la sua lista di strumenti.
• Accorcia il testo, tieni gli strumenti. Una descrizione dice cosa e quando. Il manuale passa in un documento che l'agente legge quando gli serve. Le nostre sono passate da circa 95.000 a circa 38.000 token, 2,5 volte di meno.
• Metti un tetto nella build. Senza, le definizioni ricrescono da sole.

Quanto costa la definizione di uno strumento, e chi la paga

Quando un client MCP si connette a un server, gli chiede la lista degli strumenti. Ogni voce è un nome, una descrizione scritta per il modello e uno schema JSON dei parametri. Il client trasforma quella lista in definizioni di strumenti inviate al modello: è così che il modello sa che lo strumento esiste e come chiamarlo.

Quindi ogni parola di una descrizione è input che il modello legge. Quanto spesso la legge dipende dal client:

• Claude Code rimanda gli strumenti MCP per impostazione predefinita. La sua documentazione, letta il 3 novembre 2026 con Claude Code 2.1.314 installato, dice che all'avvio della sessione vengono caricati solo i nomi degli strumenti e le istruzioni dei server, e che una definizione viene caricata tramite la ricerca degli strumenti quando a Claude serve quello strumento. Con ENABLE_TOOL_SEARCH=false, con auto sotto una soglia del 10% della finestra di contesto, sui modelli precedenti a Claude Opus 4 e Sonnet 4, o per un server marcato alwaysLoad, le definizioni vengono caricate fin dall'inizio.
• Gli altri CLI fanno diversamente. Nel nostro test del 28 ottobre, con un agente a cui si chiedeva di rispondere "OK": Claude Code partiva da 67.500 token con i nostri strumenti rimandati, Codex CLI 0.164 partiva da 25.000 token e non inviava i nostri schemi in un unico blocco, e OpenCode caricava i nostri 175 strumenti più 19 strumenti del browser alla connessione e li inviava a ogni richiesta. Stesso server, conti molto diversi.

La cache dei prompt attenua il costo quando la lista degli strumenti non cambia: dopo la prima richiesta, un prefisso stabile viene letto dalla cache a una frazione del prezzo di input. Non restituisce lo spazio. Le definizioni restano nella finestra di contesto a ogni richiesta, accanto al tuo codice e alla tua conversazione. E la modalità rimandata ha un costo tutto suo: un passaggio di ricerca prima del primo uso di ogni strumento.

Misura i tuoi in due minuti

In Claude Code, esegui /context. Suddivide la finestra per origine e segnala gli strumenti MCP rimandati o caricati su richiesta. Eseguilo in una sessione nuova del tuo progetto, prima di scrivere qualsiasi cosa, e vedi quanto costa la tua configurazione prima che il lavoro cominci.

Per qualsiasi server e qualsiasi CLI, chiedilo direttamente al server. Un server MCP su stdio parla JSON-RPC, un messaggio per riga: invii initialize, poi tools/list, e misuri cosa torna indietro. Questo script fa esattamente questo, con Node e senza alcuna dipendenza:

// Usage: node mcp-tool-cost.mjs <command that starts the server> [args...]
import { spawn } from 'node:child_process';

const [cmd, ...args] = process.argv.slice(2);
const server = spawn(cmd, args, { stdio: ['pipe', 'pipe', 'ignore'], shell: process.platform === 'win32' });
const tools = [];
let buffer = '';

const send = (msg) => server.stdin.write(JSON.stringify({ jsonrpc: '2.0', ...msg }) + '\n');
const listTools = (cursor) => send({ id: 2, method: 'tools/list', params: cursor ? { cursor } : {} });

server.stdout.on('data', (chunk) => {
  buffer += chunk;
  let end;
  while ((end = buffer.indexOf('\n')) >= 0) {
    const line = buffer.slice(0, end).trim();
    buffer = buffer.slice(end + 1);
    if (line) handle(JSON.parse(line));
  }
});

function handle(msg) {
  if (msg.id === 1) {
    send({ method: 'notifications/initialized' });
    listTools();
  } else if (msg.id === 2) {
    tools.push(...msg.result.tools);
    if (msg.result.nextCursor) listTools(msg.result.nextCursor);
    else { report(); server.kill(); }
  }
}

function report() {
  const rows = tools
    .map((tool) => ({ name: tool.name, bytes: Buffer.byteLength(JSON.stringify(tool)) }))
    .sort((a, b) => b.bytes - a.bytes);
  const total = rows.reduce((sum, row) => sum + row.bytes, 0);
  for (const row of rows.slice(0, 10)) {
    console.log(`${String(row.bytes).padStart(7)} bytes  ~${Math.round(row.bytes / 4)} tokens  ${row.name}`);
  }
  console.log(`${rows.length} tools, ${total} bytes, about ${Math.round(total / 4)} tokens`);
}

send({
  id: 1,
  method: 'initialize',
  params: { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'tool-cost', version: '1.0.0' } },
});

Lancialo con lo stesso comando che il tuo CLI usa per avviare il server, per esempio node mcp-tool-cost.mjs npx -y @playwright/mcp@latest. Stampa i dieci strumenti più pesanti e il totale. Ecco cosa abbiamo ottenuto il 3 novembre 2026:

Quattro byte per token è una stima, sufficiente per confrontare server e vedere una tendenza, non per prevedere una bolletta. I tokenizer reali variano in base al modello e al testo, come abbiamo visto quando abbiamo contato 3,8 miliardi dei nostri token.

I server di file qui sopra sono ragionevoli. Il problema è la somma: cinque server di quella taglia fanno già 20.000 token, prima ancora di un server come il nostro.

Cosa abbiamo tagliato, e cosa non abbiamo toccato

La regola che ci siamo dati: nessuno strumento tolto, nessun parametro tolto, nessun valore ammesso né campo obbligatorio tolto. Gli agenti dovevano conservare tutte le loro capacità. Poteva cambiare solo il testo.

1. La descrizione di uno strumento dice cosa e quando, in una-tre frasi. Non come. Il come era dove stavano i byte: regole, valori predefiniti, casi limite, esempi, avvertenze scritte dopo che un agente aveva usato male lo strumento una volta.
2. Un parametro ha diritto a una frase, o a niente quando il suo nome, il suo tipo e la sua lista di valori ammessi dicono già tutto. I parametri che si ripetono tra gli strumenti (project, author, id dei ticket) hanno ricevuto la stessa frase standard ovunque.
3. Il manuale è stato spostato, non cancellato. Ogni famiglia di strumenti ha un file di istruzioni che l'agente legge prima della sua prima chiamata a quella famiglia. Per il nostro strumento più grande, quello che salva un team di agenti, il riferimento completo dei campi ora viene restituito da una chiamata a uno strumento quando l'agente lo chiede, invece di viaggiare dentro lo schema.
4. Un secondo passaggio ha verificato ogni fatto. Ogni frase tolta da una descrizione è stata cercata nei file di istruzioni, e rimessa lì quando mancava.

Alcuni risultati, in byte di JSON per strumento:

In totale, 380 KB sono diventati 152 KB. Tredici strumenti superavano i 4 KB; quattro li superano ancora, per il numero di campi che portano. L'idea dietro tutto il passaggio: per scegliere uno strumento, il modello ha bisogno di sapere che esiste e quando chiamarlo. I dettagli possono aspettare il momento in cui lo usa.

Se scrivi un server MCP, Claude Code ti dà un motivo in più. Taglia a 4.096 caratteri la descrizione di uno strumento caricata fin dall'inizio, e quando confronta una ricerca con una descrizione legge solo la parte entro quel limite. Qualsiasi cosa importante oltre quel punto potrebbe non essere mai vista.

Lo stesso trucco per un file di avvio

Gli schemi degli strumenti non sono l'unico costo fisso. I nostri agenti leggono anche un file di istruzioni sugli strumenti prima di usarli, ed era cresciuto fino a 57,7 KB, circa 14.000 token, letti per intero a ogni avvio e a ogni ripresa. Un utente ci ha segnalato che un agente Codex ripreso raggiungeva il suo limite di contesto di lavoro in pochi minuti.

La correzione ha seguito la stessa idea. Il file è diventato un indice di circa 11 KB: le regole che valgono per tutti gli strumenti, e una riga per famiglia di strumenti che punta al suo file. I 31 file di famiglia vengono letti solo prima della prima chiamata a quella famiglia. Il loro testo non è cambiato, parola per parola. Un agente che tocca solo il backlog non legge mai la sezione sui database.

Funziona anche per qualsiasi CLAUDE.md o AGENTS.md lungo: tieni nel file sempre caricato ciò che serve a ogni attività, e metti un link al resto. Ne parliamo di più nella nostra guida su AGENTS.md e i file di contesto.

Un budget che fa fallire il push

Il numero che ci preoccupava di più non era 95.000. Era 78.000 una settimana prima. Ogni strumento aggiungeva un paragrafo, ogni paragrafo era ragionevole, e la somma è cresciuta del 20% in sette giorni.

Così la dimensione è diventata un controllo della build. Un file JSON contiene il budget:

{
  "totalBytes": 160000,
  "perToolBytes": 4000,
  "oversized": {
    "teams_save": 9791,
    "triggers_save": 4071,
    "backlog_update": 4253,
    "backlog_create": 4399
  }
}

Uno script avvia i nostri server MCP in una sandbox, chiede a ciascuno i suoi strumenti, misura JSON.stringify(tool) in byte ed esce con un errore quando il totale supera totalBytes o quando uno strumento supera perToolBytes. I quattro strumenti che erano già troppo grandi sono elencati con la loro dimensione: un cricchetto. Possono dimagrire, mai crescere, e quando uno dimagrisce lo script chiede di abbassare il numero. Gira prima di ogni push e nella build di release. Alzare il tetto è possibile, ma è una decisione scritta nel file, non un modo per far passare il controllo.

Il 3 novembre, sei giorni dopo, lo stesso controllo legge 203 strumenti e 159.957 byte: dodici strumenti aggiunti, 43 byte sotto il tetto. Il prossimo strumento dovrà farsi spazio da solo. È esattamente a questo che serve il controllo.

Disattiva ciò che non usi

Il token più economico è quello dello strumento che il tuo agente non vede mai.

• Limita i server ai progetti che ne hanno bisogno. Un server dichiarato a livello utente ti segue in ogni repository. In Claude Code, un .mcp.json di progetto lo tiene dove è utile.
• Riserva alwaysLoad a una manciata di strumenti. La documentazione di Claude Code lo dice chiaramente: ogni strumento caricato fin dall'inizio consuma contesto che altrimenti sarebbe disponibile per la tua conversazione.
• Tieni d'occhio cosa aggiungono i risultati degli strumenti, non solo le definizioni. Uno strumento che restituisce una pagina o una tabella intera può costare di più in una chiamata di quanto costi la sua definizione in tutta la giornata.

In AgentsRoom, Impostazioni > Strumenti AgentsRoom elenca ogni famiglia dei nostri strumenti con il suo peso, e puoi disattivare una famiglia o un singolo strumento, per tutti i progetti, un progetto, una cartella o un singolo agente. Uno strumento disattivato non viene nemmeno presentato all'agente, quindi non costa contesto. La pagina AgentsRoom MCP descrive gli strumenti, e la traccia della sessione mostra cosa ha riempito il contesto di un agente, strumenti MCP compresi, ordinato per dimensione.

Cosa non abbiamo cambiato

Dalla stessa misurazione sono usciti altri due costi, e li abbiamo lasciati come erano, di proposito.

• Il brief di avvio che dice a ogni agente il suo ruolo e come riportare il suo stato: una mediana di circa 5.000 token per Claude, circa il 2,5% di una finestra da 200.000 token, e letto dalla cache dalla seconda richiesta in poi.
• Il file di stato che ogni agente scrive alla fine di un turno: misurato su 71 trascrizioni locali di Claude, circa il 2,5% dei token di contesto.

Ridurre l'uno o l'altro avrebbe fatto risparmiare meno del 3% della finestra e messo a rischio la qualità del lavoro degli agenti. Le definizioni degli strumenti erano 95.000 token. È lì che abbiamo speso il tempo.

Le domande che la gente fa davvero

Quanti token consumano gli strumenti MCP?

Ogni strumento costa la sua definizione intera: nome, descrizione e schema di input, inviati come JSON. Una regola approssimativa è 4 byte per token. Misurato il 3 novembre 2026: il server filesystem ufficiale elenca 14 strumenti per circa 3.100 token, Playwright MCP 25 strumenti per circa 5.300. Gli strumenti di AgentsRoom pesavano circa 95.000 token prima che li accorciassimo, circa 40.000 oggi.

Claude Code carica tutti gli strumenti MCP nella finestra di contesto?

Non per impostazione predefinita. La ricerca degli strumenti di Claude Code (tool search) rimanda le definizioni degli strumenti MCP: all'avvio della sessione vengono caricati solo i nomi degli strumenti e le istruzioni dei server, e Claude carica una definizione quando gli serve quello strumento. ENABLE_TOOL_SEARCH=false, un modello precedente a Claude Opus 4 e Sonnet 4, o un server marcato alwaysLoad rimettono le definizioni nel contesto fin dall'inizio.

I server MCP riducono il consumo di token?

Possono farlo, quando uno strumento restituisce una risposta breve al posto di qualcosa che l'agente altrimenti leggerebbe per intero, come una query su un database invece di un dump completo. Ma le definizioni costano contesto, e anche i risultati: Claude Code avvisa quando un risultato MCP supera i 10.000 token e lo taglia a 25.000 per impostazione predefinita. Un server MCP fa risparmiare token solo quando i suoi risultati sono più piccoli di ciò che sostituisce.

Come vedo quanto contesto occupano i miei strumenti MCP?

In Claude Code, esegui /context: suddivide il contesto per origine e segnala gli strumenti MCP rimandati. Per qualsiasi server e qualsiasi CLI, chiedi al server la sua lista di strumenti e misura il JSON, che è quello che fa lo script di 40 righe di questo articolo.

Cosa rende buona la descrizione di uno strumento MCP?

Da una a tre frasi che dicono cosa fa lo strumento e quando chiamarlo, con le parole che un agente cercherebbe messe all'inizio. Un parametro ha diritto a una frase, o a niente quando il suo nome, il suo tipo e i suoi valori ammessi dicono già tutto. Regole, casi limite ed esempi lunghi vanno in un documento che l'agente legge quando gli serve. In ogni caso, Claude Code taglia a 4.096 caratteri una descrizione caricata fin dall'inizio.

Come impedisco alle definizioni degli strumenti di tornare a crescere?

Dagli un budget che la build possa verificare. Teniamo un file JSON con un tetto totale e un tetto per strumento, uno script che avvia i nostri server MCP, misura ogni strumento ed esce con un errore oltre uno dei due limiti, e lo lanciamo prima di ogni push. Gli strumenti che erano già troppo grandi possono dimagrire, mai crescere.

In breve

I tuoi strumenti MCP sono testo che il modello legge, e nessuno rilegge quel testo come rilegge il codice. Misuralo una volta: /context in Claude Code, o lo script qui sopra per qualsiasi server. Poi fai dire a ogni descrizione cosa e quando, sposta il come in un file che l'agente legge quando gli serve, e metti un numero nella tua build così che non possa tornare a crescere di nascosto.

Siamo passati da circa 95.000 a circa 38.000 token senza togliere uno strumento. Se fai girare più agenti con gli stessi strumenti, AgentsRoom si scarica gratis, e la pagina Server MCP mostra come dichiarare un server una volta sola per tutti i CLI e tutti i progetti.