MCP-tokengebruik verminderen: zo hebben we onze tooldefinities 60% kleiner gemaakt

Op 27 oktober zegde een betalende gebruiker zijn AgentsRoom-abonnement op, met tokens als reden. Voordat we daarover in discussie gingen, hebben we gemeten wat onze app toevoegt aan elke agent die hij start.

Het grootste getal zat niet waar we het verwachtten. Onze startinstructies waren klein. De MCP-tools die we elke agent meegeven (backlog, projectgeheugen, agentmail, terminals, SSH, databases en de rest) waren 191 tools en ongeveer 380 KB JSON. Bij grofweg 4 bytes per token is dat ongeveer 95.000 tokens aan tooldefinities. Een week eerder was het 78.000. Niemand had dat besloten: elke nieuwe tool had gewoon zijn alinea toegevoegd.

Wij bouwen AgentsRoom, een desktop-app die Claude Code, Codex en andere coding-CLI's naast elkaar draait en ze deze tools geeft. Dit is wat we hebben gemeten, wat we hebben ingekort zonder één tool te verwijderen, en de controle die voorkomt dat het terugkomt. Je kunt dit allemaal toepassen op je eigen MCP-servers.

Het korte antwoord

• Een tooldefinitie is JSON dat het model bij elk verzoek kan lezen: naam, beschrijving, invoerschema. Reken op ongeveer 4 bytes per token.
• Of je dat bij elke beurt betaalt, hangt af van de CLI. Claude Code stelt MCP-tools standaard uit en laadt een definitie wanneer het die nodig heeft. Sommige CLI's sturen elk schema mee met elk verzoek.
• Meet voordat je inkort. /context in Claude Code, of een script van 40 regels dat elke willekeurige server om zijn lijst met tools vraagt.
• Kort de tekst in, houd de tools. Een beschrijving zegt wat en wanneer. De handleiding verhuist naar een document dat de agent op verzoek leest. De onze gingen van ongeveer 95.000 naar ongeveer 38.000 tokens, 2,5 keer minder.
• Zet een plafond in de build. Zonder plafond groeien definities vanzelf weer aan.

Wat een tooldefinitie kost, en wie ervoor betaalt

Wanneer een MCP-client verbinding maakt met een server, vraagt hij om de lijst met tools. Elk item bestaat uit een naam, een beschrijving die voor het model is geschreven en een JSON-schema van de parameters. De client maakt van die lijst tooldefinities die naar het model worden gestuurd: zo weet het model dat de tool bestaat en hoe het hem aanroept.

Elk woord van een beschrijving is dus invoer die het model leest. Hoe vaak het die leest, hangt af van de client:

• Claude Code stelt MCP-tools standaard uit. De documentatie, gelezen op 3 november 2026 met Claude Code 2.1.314 geïnstalleerd, zegt dat bij de start van een sessie alleen de toolnamen en de serverinstructies worden geladen, en dat een definitie via het zoeken naar tools wordt geladen wanneer Claude die tool nodig heeft. Met ENABLE_TOOL_SEARCH=false, met auto onder een drempel van 10% van het contextvenster, op modellen ouder dan Claude Opus 4 en Sonnet 4, of voor een server gemarkeerd met alwaysLoad worden de definities meteen vanaf het begin geladen.
• Andere CLI's doen het anders. In onze eigen test van 28 oktober, met een agent die alleen "OK" moest antwoorden: Claude Code opende op 67.500 tokens met onze tools uitgesteld, Codex CLI 0.164 opende op 25.000 tokens en stuurde onze schema's niet als één blok, en OpenCode laadde onze 175 tools plus 19 browsertools bij het verbinden en stuurde ze mee met elk verzoek. Dezelfde server, heel andere rekeningen.

Prompt caching verzacht de kosten als de lijst met tools niet verandert: na het eerste verzoek wordt een stabiel voorvoegsel uit de cache gelezen voor een fractie van de invoerprijs. Het geeft de ruimte niet terug. De definities staan bij elk verzoek nog steeds in het contextvenster, naast je code en je gesprek. En de uitgestelde modus heeft zijn eigen kosten: een zoekstap vóór het eerste gebruik van elke tool.

Meet de jouwe in twee minuten

In Claude Code voer je /context uit. Het splitst het venster op per bron en markeert MCP-tools die uitgesteld zijn of op verzoek worden geladen. Draai het in een verse sessie in je project, voordat je iets typt, en je ziet wat je setup kost voordat het werk begint.

Voor elke server en elke CLI vraag je het de server rechtstreeks. Een MCP-server via stdio spreekt JSON-RPC, één bericht per regel: je stuurt initialize, dan tools/list, en meet wat er terugkomt. Dit script doet precies dat, met Node en zonder enige afhankelijkheid:

// 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' } },
});

Start het met hetzelfde commando dat je CLI gebruikt om de server te starten, bijvoorbeeld node mcp-tool-cost.mjs npx -y @playwright/mcp@latest. Het toont de tien zwaarste tools en het totaal. Dit kregen we op 3 november 2026:

Vier bytes per token is een schatting, goed genoeg om servers te vergelijken en een trend te zien, niet om een rekening te voorspellen. Echte tokenizers verschillen per model en per tekst, zoals we merkten toen we 3,8 miljard van onze eigen tokens telden.

De bestandsservers hierboven zijn redelijk. Het probleem is de som: vijf servers van die omvang zijn al 20.000 tokens, nog vóór een server zoals de onze.

Wat we hebben ingekort, en wat we niet hebben aangeraakt

De regel die we onszelf oplegden: geen tool verwijderd, geen parameter verwijderd, geen toegestane waarde of verplicht veld verwijderd. Agents moesten al hun mogelijkheden houden. Alleen de tekst mocht veranderen.

1. Een toolbeschrijving zegt wat en wanneer, in één tot drie zinnen. Niet hoe. In het hoe zaten de bytes: regels, standaardwaarden, randgevallen, voorbeelden, waarschuwingen die geschreven waren nadat een agent de tool een keer verkeerd had gebruikt.
2. Een parameter krijgt één zin, of niets als zijn naam, type en lijst met toegestane waarden al alles zeggen. Parameters die bij meerdere tools terugkomen (project, author, ticket-id's) kregen overal dezelfde standaardzin.
3. De handleiding is verhuisd, niet verwijderd. Elke familie van tools heeft een instructiebestand dat de agent leest vóór zijn eerste aanroep van die familie. Voor onze grootste tool, die een team van agents opslaat, wordt de volledige veldreferentie nu teruggegeven door een toolaanroep wanneer de agent erom vraagt, in plaats van mee te reizen in het schema.
4. Een tweede ronde controleerde elk feit. Elke zin die uit een beschrijving was gehaald, werd opgezocht in de instructiebestanden, en daar teruggezet als hij ontbrak.

Een deel van de resultaten, in bytes JSON per tool:

In totaal werd 380 KB 152 KB. Dertien tools zaten boven 4 KB; vier zitten er nog steeds boven, door het aantal velden dat ze dragen. Het idee achter de hele ronde: om een tool te kiezen, moet het model weten dat hij bestaat en wanneer het hem moet aanroepen. De details kunnen wachten tot het moment dat het hem gebruikt.

Als je een MCP-server schrijft, geeft Claude Code je nog een reden. Het kapt een toolbeschrijving die vooraf wordt geladen af bij 4.096 tekens, en wanneer het een zoekopdracht vergelijkt met een beschrijving, leest het alleen het deel binnen die grens. Alles wat belangrijk is na dat punt wordt misschien nooit gezien.

Dezelfde truc voor een opstartbestand

Toolschema's zijn niet de enige vaste kosten. Onze agents lezen ook een instructiebestand over de tools voordat ze die gebruiken, en dat was gegroeid tot 57,7 KB, ongeveer 14.000 tokens, volledig gelezen bij elke start en elke hervatting. Een gebruiker meldde dat een hervatte Codex-agent binnen enkele minuten de grens van zijn werkcontext bereikte.

De oplossing volgde hetzelfde idee. Het bestand werd een index van ongeveer 11 KB: de regels die voor elke tool gelden, en één regel per familie van tools die naar haar eigen bestand verwijst. De 31 familiebestanden worden pas gelezen vóór de eerste aanroep van die familie. Hun tekst is niet veranderd, woord voor woord. Een agent die alleen de backlog aanraakt, leest nooit de sectie over databases.

Dit werkt ook voor elke lange CLAUDE.md of AGENTS.md: houd in het bestand dat altijd wordt geladen wat elke taak nodig heeft, en link naar de rest. We schreven daar meer over in onze gids over AGENTS.md en contextbestanden.

Een budget dat de push laat mislukken

Het getal dat ons het meest zorgen baarde was niet 95.000. Het was 78.000 een week eerder. Elke tool voegde een alinea toe, elke alinea was redelijk, en de som groeide met 20% in zeven dagen.

Dus werd de omvang een controle in de build. Eén JSON-bestand bevat het budget:

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

Een script start onze MCP-servers in een sandbox, vraagt elk om zijn tools, meet JSON.stringify(tool) in bytes en stopt met een fout als het totaal boven totalBytes komt of als een tool boven perToolBytes komt. De vier tools die al te groot waren, staan in de lijst met hun omvang: een ratel. Ze mogen krimpen, nooit groeien, en als er een krimpt, vraagt het script om het getal te verlagen. Het draait voor elke push en in de release-build. Het plafond verhogen kan, maar het is een beslissing die in het bestand staat, geen manier om de controle te laten slagen.

Op 3 november, zes dagen later, leest dezelfde controle 203 tools en 159.957 bytes: twaalf tools erbij, 43 bytes onder het plafond. De volgende tool zal zelf ruimte moeten maken. Precies daarvoor is de controle er.

Zet uit wat je niet gebruikt

Het goedkoopste token is dat van een tool die je agent nooit ziet.

• Beperk servers tot de projecten die ze nodig hebben. Een server die op gebruikersniveau is gedeclareerd, volgt je naar elke repository. In Claude Code houdt een .mcp.json van het project hem waar hij nuttig is.
• Houd alwaysLoad voor een handvol tools. De documentatie van Claude Code zegt het duidelijk: elke tool die vooraf wordt geladen, verbruikt context die anders beschikbaar zou zijn voor je gesprek.
• Let op wat toolresultaten toevoegen, niet alleen op de definities. Een tool die een hele pagina of tabel teruggeeft, kan in één aanroep meer kosten dan zijn definitie de hele dag.

In AgentsRoom toont Instellingen > AgentsRoom-tools elke familie van onze tools met haar gewicht, en je kunt een familie of één tool uitzetten, voor alle projecten, één project, een map of één agent. Een uitgezette tool wordt de agent helemaal niet getoond, dus kost hij geen context. De pagina over AgentsRoom MCP beschrijft de tools, en de sessietrace laat zien wat de context van een agent heeft gevuld, MCP-tools inbegrepen, gerangschikt op grootte.

Wat we niet hebben veranderd

Uit dezelfde meting kwamen nog twee kosten, en die hebben we bewust laten staan.

• De startbriefing die elke agent zijn rol vertelt en hoe hij zijn status meldt: een mediaan van ongeveer 5.000 tokens voor Claude, ongeveer 2,5% van een venster van 200.000 tokens, en vanaf het tweede verzoek uit de cache gelezen.
• Het statusbestand dat elke agent aan het einde van een beurt schrijft: gemeten op 71 lokale Claude-transcripten, ongeveer 2,5% van de contexttokens.

Een van beide verkleinen had minder dan 3% van het venster bespaard en de kwaliteit van het werk van de agents op het spel gezet. De tooldefinities waren 95.000 tokens. Daar is de tijd in gaan zitten.

Vragen die mensen echt stellen

Hoeveel tokens gebruiken MCP-tools?

Elke tool kost zijn volledige definitie: naam, beschrijving en invoerschema, verstuurd als JSON. Een ruwe vuistregel is 4 bytes per token. Gemeten op 3 november 2026: de officiële filesystem-server toont 14 tools voor ongeveer 3.100 tokens, Playwright MCP 25 tools voor ongeveer 5.300. De AgentsRoom-tools wogen ongeveer 95.000 tokens voordat we ze inkortten, vandaag ongeveer 40.000.

Laadt Claude Code elke MCP-tool in het contextvenster?

Niet standaard. Het zoeken naar tools van Claude Code (tool search) stelt de definities van MCP-tools uit: alleen de toolnamen en de serverinstructies worden geladen bij de start van de sessie, en Claude laadt een definitie wanneer het die tool nodig heeft. ENABLE_TOOL_SEARCH=false, een model ouder dan Claude Opus 4 en Sonnet 4, of een server gemarkeerd met alwaysLoad zet de definities weer meteen vanaf het begin in de context.

Verminderen MCP-servers het tokengebruik?

Dat kan, als een tool een kort antwoord teruggeeft in plaats van iets wat de agent anders volledig zou lezen, zoals een databasequery in plaats van een dump. Maar de definities kosten context, en de resultaten ook: Claude Code waarschuwt als één MCP-resultaat boven de 10.000 tokens komt en kapt het standaard af bij 25.000. Een MCP-server bespaart alleen tokens als zijn resultaten kleiner zijn dan wat hij vervangt.

Hoe zie ik hoeveel context mijn MCP-tools innemen?

Voer in Claude Code /context uit: het splitst de context op per bron en markeert de MCP-tools die uitgesteld zijn. Voor elke server en elke CLI vraag je de server om zijn lijst met tools en meet je de JSON, en dat is precies wat het script van 40 regels in dit artikel doet.

Wat maakt een goede beschrijving van een MCP-tool?

Eén tot drie zinnen die zeggen wat de tool doet en wanneer je hem aanroept, met de woorden waarop een agent zou zoeken vooraan. Een parameter krijgt één zin, of niets als zijn naam, type en toegestane waarden het al zeggen. Regels, randgevallen en lange voorbeelden horen in een document dat de agent op verzoek leest. Claude Code kapt een beschrijving die vooraf wordt geladen sowieso af bij 4.096 tekens.

Hoe voorkom ik dat tooldefinities weer groeien?

Geef ze een budget dat de build kan controleren. Wij hebben een JSON-bestand met een totaal plafond en een plafond per tool, een script dat onze MCP-servers start, elke tool meet en met een fout stopt boven een van beide grenzen, en we draaien het voor elke push. Tools die al te groot waren mogen krimpen, nooit groeien.

De korte versie

Je MCP-tools zijn tekst die het model leest, en niemand reviewt die tekst zoals code wordt gereviewd. Meet het één keer: /context in Claude Code, of het script hierboven voor elke server. Laat daarna elke beschrijving zeggen wat en wanneer, verplaats het hoe naar een bestand dat de agent leest wanneer hij het nodig heeft, en zet een getal in je build zodat het niet terug kan sluipen.

We gingen van ongeveer 95.000 naar ongeveer 38.000 tokens zonder één tool te verwijderen. Als je meerdere agents met dezelfde tools draait: AgentsRoom is gratis te downloaden, en de pagina over MCP-servers laat zien hoe je een server één keer declareert voor elke CLI en elk project.