MCP-Tokenverbrauch reduzieren: Wie wir unsere Tool-Definitionen um 60 % gekürzt haben

Am 27. Oktober hat ein zahlender Nutzer sein AgentsRoom-Abo gekündigt und als Grund die Tokens genannt. Bevor wir darüber diskutiert haben, haben wir gemessen, was unsere App jedem Agenten hinzufügt, den sie startet.

Die größte Zahl lag nicht dort, wo wir sie erwartet hatten. Unsere Startanweisungen waren klein. Die MCP-Tools, die wir jedem Agenten mitgeben (Backlog, Projektgedächtnis, Agenten-Mail, Terminals, SSH, Datenbanken und der Rest), waren 191 Tools und etwa 380 KB JSON. Bei grob 4 Bytes pro Token sind das etwa 95.000 Tokens an Tool-Definitionen. Eine Woche vorher waren es 78.000. Niemand hatte das beschlossen: Jedes neue Tool hatte einfach seinen Absatz hinzugefügt.

Wir entwickeln AgentsRoom, eine Desktop-App, die Claude Code, Codex und andere Coding-CLIs nebeneinander laufen lässt und ihnen diese Tools gibt. Hier steht, was wir gemessen haben, was wir gekürzt haben, ohne ein einziges Tool zu entfernen, und welche Prüfung verhindert, dass es zurückkommt. Du kannst all das auf deine eigenen MCP-Server anwenden.

Die kurze Antwort

• Eine Tool-Definition ist JSON, das das Modell bei jeder Anfrage lesen kann: Name, Beschreibung, Eingabeschema. Rechne mit etwa 4 Bytes pro Token.
• Ob du das bei jedem Zug bezahlst, hängt vom CLI ab. Claude Code lädt MCP-Tools standardmäßig verzögert und lädt eine Definition erst, wenn es sie braucht. Manche CLIs schicken jedes Schema mit jeder Anfrage.
• Miss, bevor du kürzt. /context in Claude Code, oder ein 40-Zeilen-Skript, das jeden beliebigen Server nach seiner Tool-Liste fragt.
• Kürze den Text, behalte die Tools. Eine Beschreibung sagt, was und wann. Die Anleitung wandert in ein Dokument, das der Agent bei Bedarf liest. Unsere gingen von etwa 95.000 auf etwa 38.000 Tokens zurück, 2,5-mal weniger.
• Setz eine Obergrenze in den Build. Ohne sie wachsen die Definitionen von selbst wieder.

Was eine Tool-Definition kostet, und wer sie bezahlt

Wenn sich ein MCP-Client mit einem Server verbindet, fragt er nach der Liste der Tools. Jeder Eintrag besteht aus einem Namen, einer für das Modell geschriebenen Beschreibung und einem JSON-Schema der Parameter. Der Client macht aus dieser Liste Tool-Definitionen, die an das Modell geschickt werden: So weiß das Modell, dass das Tool existiert und wie man es aufruft.

Jedes Wort einer Beschreibung ist also Eingabe, die das Modell liest. Wie oft es sie liest, hängt vom Client ab:

• Claude Code lädt MCP-Tools standardmäßig verzögert. Seine Dokumentation, gelesen am 3. November 2026 mit installiertem Claude Code 2.1.314, sagt, dass beim Sitzungsstart nur die Tool-Namen und die Server-Anweisungen geladen werden und dass eine Definition über die Tool-Suche nachgeladen wird, wenn Claude dieses Tool braucht. Mit ENABLE_TOOL_SEARCH=false, mit auto unterhalb einer Schwelle von 10 % des Kontextfensters, bei Modellen, die älter sind als Claude Opus 4 und Sonnet 4, oder für einen mit alwaysLoad markierten Server werden die Definitionen von Anfang an geladen.
• Andere CLIs machen es anders. In unserem eigenen Test am 28. Oktober, mit einem Agenten, der nur „OK“ antworten sollte: Claude Code startete mit 67.500 Tokens, unsere Tools verzögert geladen, Codex CLI 0.164 startete mit 25.000 Tokens und schickte unsere Schemas nicht als einen Block, und OpenCode lud unsere 175 Tools plus 19 Browser-Tools beim Verbinden und schickte sie mit jeder Anfrage. Derselbe Server, sehr unterschiedliche Rechnungen.

Prompt-Caching mildert die Kosten, wenn sich die Tool-Liste nicht ändert: Nach der ersten Anfrage wird ein stabiles Präfix zu einem Bruchteil des Eingabepreises aus dem Cache gelesen. Den Platz gibt es aber nicht zurück. Die Definitionen stehen weiterhin bei jeder Anfrage im Kontextfenster, neben deinem Code und deiner Unterhaltung. Und der verzögerte Modus hat seine eigenen Kosten: einen Suchschritt vor der ersten Nutzung jedes Tools.

Miss deine in zwei Minuten

In Claude Code führst du /context aus. Es schlüsselt das Fenster nach Quelle auf und kennzeichnet MCP-Tools, die verzögert oder bei Bedarf geladen werden. Führ es in einer frischen Sitzung in deinem Projekt aus, bevor du irgendetwas tippst, und du siehst, was dein Setup kostet, bevor die Arbeit beginnt.

Für jeden Server und jedes CLI fragst du den Server direkt. Ein MCP-Server über stdio spricht JSON-RPC, eine Nachricht pro Zeile: Du schickst initialize, dann tools/list, und misst, was zurückkommt. Dieses Skript macht genau das, mit Node und ohne jede Abhängigkeit:

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

Starte es mit demselben Befehl, mit dem dein CLI den Server startet, zum Beispiel node mcp-tool-cost.mjs npx -y @playwright/mcp@latest. Es gibt die zehn schwersten Tools und die Summe aus. Das haben wir am 3. November 2026 erhalten:

Vier Bytes pro Token ist eine Schätzung, gut genug, um Server zu vergleichen und einen Trend zu sehen, nicht, um eine Rechnung vorherzusagen. Echte Tokenizer variieren je nach Modell und Text, wie wir gemerkt haben, als wir 3,8 Milliarden unserer eigenen Tokens gezählt haben.

Die Dateiserver oben sind vernünftig. Das Problem ist die Summe: Fünf Server dieser Größe sind schon 20.000 Tokens, noch vor einem Server wie unserem.

Was wir gekürzt haben, und was wir nicht angefasst haben

Die Regel, die wir uns gesetzt haben: kein Tool entfernt, kein Parameter entfernt, kein erlaubter Wert und kein Pflichtfeld entfernt. Die Agenten mussten jede Fähigkeit behalten. Nur der Text durfte sich ändern.

1. Eine Tool-Beschreibung sagt in ein bis drei Sätzen, was und wann. Nicht wie. Im Wie steckten die Bytes: Regeln, Standardwerte, Grenzfälle, Beispiele, Warnungen, die geschrieben wurden, nachdem ein Agent das Tool einmal falsch benutzt hatte.
2. Ein Parameter bekommt einen Satz, oder gar nichts, wenn sein Name, sein Typ und seine Liste erlaubter Werte schon alles sagen. Parameter, die sich über Tools hinweg wiederholen (project, author, Ticket-IDs), bekamen überall denselben Standardsatz.
3. Die Anleitung ist umgezogen, nicht gelöscht worden. Jede Tool-Familie hat eine Anweisungsdatei, die der Agent vor seinem ersten Aufruf dieser Familie liest. Bei unserem größten Tool, dem, das ein Team von Agenten speichert, wird die vollständige Feldreferenz jetzt von einem Tool-Aufruf zurückgegeben, wenn der Agent danach fragt, statt im Schema mitzufahren.
4. Ein zweiter Durchgang hat jeden Fakt geprüft. Jeder Satz, der aus einer Beschreibung entfernt wurde, wurde in den Anweisungsdateien gesucht und dort ergänzt, wenn er fehlte.

Einige der Ergebnisse, in Bytes JSON pro Tool:

Insgesamt wurden aus 380 KB 152 KB. Dreizehn Tools lagen über 4 KB; vier liegen noch darüber, wegen der Zahl der Felder, die sie tragen. Die Idee hinter dem ganzen Durchgang: Um ein Tool auszuwählen, muss das Modell wissen, dass es existiert und wann es aufzurufen ist. Die Details können bis zu dem Moment warten, in dem es das Tool benutzt.

Wenn du einen MCP-Server schreibst, gibt dir Claude Code noch einen Grund mehr. Es schneidet eine von Anfang an geladene Tool-Beschreibung bei 4.096 Zeichen ab, und wenn es eine Suche mit einer Beschreibung abgleicht, liest es nur den Teil innerhalb dieser Grenze. Alles Wichtige nach dieser Stelle wird womöglich nie gesehen.

Derselbe Trick für eine Startdatei

Tool-Schemas sind nicht die einzigen Fixkosten. Unsere Agenten lesen außerdem eine Anweisungsdatei über die Tools, bevor sie sie benutzen, und die war auf 57,7 KB gewachsen, etwa 14.000 Tokens, bei jedem Start und jeder Fortsetzung komplett gelesen. Ein Nutzer meldete, dass ein fortgesetzter Codex-Agent innerhalb von Minuten an seine Grenze für den Arbeitskontext stieß.

Die Lösung folgte derselben Idee. Die Datei wurde zu einem Index von etwa 11 KB: die Regeln, die für jedes Tool gelten, und eine Zeile pro Tool-Familie, die auf deren eigene Datei verweist. Die 31 Familiendateien werden erst vor dem ersten Aufruf der jeweiligen Familie gelesen. Ihr Text hat sich nicht geändert, Wort für Wort. Ein Agent, der nur das Backlog anfasst, liest den Abschnitt über Datenbanken nie.

Das funktioniert auch für jede lange CLAUDE.md oder AGENTS.md: Behalte in der immer geladenen Datei, was jede Aufgabe braucht, und verlinke den Rest. Mehr dazu steht in unserem Leitfaden zu AGENTS.md und Kontextdateien.

Ein Budget, das den Push scheitern lässt

Die Zahl, die uns am meisten beunruhigt hat, war nicht 95.000. Es war 78.000 eine Woche vorher. Jedes Tool fügte einen Absatz hinzu, jeder Absatz war vernünftig, und die Summe wuchs in sieben Tagen um 20 %.

Also wurde die Größe zu einer Build-Prüfung. Eine JSON-Datei enthält das Budget:

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

Ein Skript startet unsere MCP-Server in einer Sandbox, fragt jeden nach seinen Tools, misst JSON.stringify(tool) in Bytes und beendet sich mit einem Fehler, wenn die Summe totalBytes überschreitet oder ein Tool perToolBytes überschreitet. Die vier Tools, die schon zu groß waren, stehen mit ihrer Größe in der Liste: eine Ratsche. Sie dürfen schrumpfen, nie wachsen, und wenn eines schrumpft, verlangt das Skript, die Zahl zu senken. Es läuft vor jedem Push und im Release-Build. Die Obergrenze anzuheben ist möglich, aber das ist eine Entscheidung, die in der Datei steht, kein Weg, die Prüfung zu bestehen.

Am 3. November, sechs Tage später, liest dieselbe Prüfung 203 Tools und 159.957 Bytes: zwölf Tools hinzugekommen, 43 Bytes unter der Obergrenze. Das nächste Tool wird sich selbst Platz schaffen müssen. Genau dafür ist die Prüfung da.

Schalte ab, was du nicht nutzt

Der billigste Token ist der eines Tools, das dein Agent nie sieht.

• Beschränke Server auf die Projekte, die sie brauchen. Ein auf Benutzerebene deklarierter Server folgt dir in jedes Repository. In Claude Code hält eine projektbezogene .mcp.json ihn dort, wo er nützlich ist.
• Behalte alwaysLoad einer Handvoll Tools vor. Die Dokumentation von Claude Code sagt es klar: Jedes von Anfang an geladene Tool verbraucht Kontext, der sonst für deine Unterhaltung zur Verfügung stünde.
• Achte darauf, was Tool-Ergebnisse hinzufügen, nicht nur die Definitionen. Ein Tool, das eine ganze Seite oder Tabelle zurückgibt, kann mit einem Aufruf mehr kosten als seine Definition den ganzen Tag.

In AgentsRoom listet Einstellungen > AgentsRoom-Tools jede Familie unserer Tools mit ihrem Gewicht auf, und du kannst eine Familie oder ein einzelnes Tool abschalten, für alle Projekte, ein Projekt, einen Ordner oder einen einzelnen Agenten. Ein abgeschaltetes Tool wird dem Agenten gar nicht erst angezeigt und kostet also keinen Kontext. Die Seite zu AgentsRoom MCP beschreibt die Tools, und der Sitzungs-Trace zeigt, was den Kontext eines Agenten gefüllt hat, MCP-Tools inklusive, nach Größe sortiert.

Was wir nicht geändert haben

Zwei weitere Kosten kamen bei derselben Messung heraus, und wir haben sie bewusst so gelassen.

• Das Start-Briefing, das jedem Agenten seine Rolle sagt und wie er seinen Status meldet: ein Median von etwa 5.000 Tokens für Claude, etwa 2,5 % eines Fensters von 200.000 Tokens, und ab der zweiten Anfrage aus dem Cache gelesen.
• Die Statusdatei, die jeder Agent am Ende eines Zugs schreibt: gemessen an 71 lokalen Claude-Transkripten, etwa 2,5 % der Kontext-Tokens.

Eines davon zu verkleinern hätte weniger als 3 % des Fensters gespart und die Qualität der Arbeit der Agenten aufs Spiel gesetzt. Die Tool-Definitionen waren 95.000 Tokens. Dort ist die Zeit hingeflossen.

Fragen, die wirklich gestellt werden

Wie viele Tokens verbrauchen MCP-Tools?

Jedes Tool kostet seine gesamte Definition: Name, Beschreibung und Eingabeschema, als JSON geschickt. Als Faustregel gelten 4 Bytes pro Token. Gemessen am 3. November 2026: Der offizielle Filesystem-Server listet 14 Tools für etwa 3.100 Tokens, Playwright MCP 25 Tools für etwa 5.300. Die AgentsRoom-Tools wogen etwa 95.000 Tokens, bevor wir sie gekürzt haben, heute etwa 40.000.

Lädt Claude Code jedes MCP-Tool ins Kontextfenster?

Nicht standardmäßig. Die Tool-Suche von Claude Code (tool search) lädt die Definitionen der MCP-Tools verzögert: Beim Sitzungsstart werden nur die Tool-Namen und die Server-Anweisungen geladen, und Claude lädt eine Definition, wenn es das Tool braucht. ENABLE_TOOL_SEARCH=false, ein Modell, das älter ist als Claude Opus 4 und Sonnet 4, oder ein mit alwaysLoad markierter Server bringen die Definitionen von Anfang an zurück in den Kontext.

Senken MCP-Server den Tokenverbrauch?

Das können sie, wenn ein Tool eine kurze Antwort liefert statt etwas, das der Agent sonst komplett lesen würde, etwa eine Datenbankabfrage statt eines Dumps. Aber die Definitionen kosten Kontext, und die Ergebnisse auch: Claude Code warnt, wenn ein MCP-Ergebnis 10.000 Tokens überschreitet, und schneidet es standardmäßig bei 25.000 ab. Ein MCP-Server spart nur dann Tokens, wenn seine Ergebnisse kleiner sind als das, was er ersetzt.

Wie sehe ich, wie viel Kontext meine MCP-Tools belegen?

Führ in Claude Code /context aus: Es schlüsselt den Kontext nach Quelle auf und kennzeichnet die verzögert geladenen MCP-Tools. Für jeden Server und jedes CLI fragst du den Server nach seiner Tool-Liste und misst das JSON, genau das macht das 40-Zeilen-Skript in diesem Artikel.

Was macht eine gute MCP-Tool-Beschreibung aus?

Ein bis drei Sätze, die sagen, was das Tool tut und wann man es aufruft, mit den Wörtern, nach denen ein Agent suchen würde, möglichst weit vorn. Ein Parameter bekommt einen Satz, oder nichts, wenn Name, Typ und erlaubte Werte es schon sagen. Regeln, Grenzfälle und lange Beispiele gehören in ein Dokument, das der Agent bei Bedarf liest. Claude Code schneidet eine von Anfang an geladene Beschreibung ohnehin bei 4.096 Zeichen ab.

Wie verhindere ich, dass Tool-Definitionen wieder wachsen?

Gib ihnen ein Budget, das der Build prüfen kann. Wir haben eine JSON-Datei mit einer Gesamtobergrenze und einer Obergrenze pro Tool, ein Skript, das unsere MCP-Server startet, jedes Tool misst und mit einem Fehler endet, sobald eine der beiden Grenzen überschritten ist, und wir lassen es vor jedem Push laufen. Tools, die schon zu groß waren, dürfen schrumpfen, nie wachsen.

Die Kurzfassung

Deine MCP-Tools sind Text, den das Modell liest, und niemand prüft diesen Text so, wie man Code prüft. Miss ihn einmal: /context in Claude Code oder das Skript oben für jeden Server. Dann lass jede Beschreibung sagen, was und wann, verschiebe das Wie in eine Datei, die der Agent liest, wenn er sie braucht, und setz eine Zahl in deinen Build, damit nichts zurückdriften kann.

Wir sind von etwa 95.000 auf etwa 38.000 Tokens gekommen, ohne ein Tool zu entfernen. Wenn du mehrere Agenten mit denselben Tools laufen lässt: AgentsRoom ist kostenlos herunterladbar, und die Seite zu MCP-Servern zeigt, wie du einen Server einmal für jedes CLI und jedes Projekt deklarierst.