MCP Tool Search: Wie wir 120K Tokens an Tool-Schemas verzögert geladen haben

Die versteckten Kosten, die uns wochenlang nicht aufgefallen sind

Wenn du einen MCP-Server (Model Context Protocol) in Claude Code installierst, bekommst du Tools. Jede Menge Tools. Allein der GitHub MCP Server stellt 35 zur Verfügung — für Issues, Pull Requests, Branches, Kommentare, Releases, Workflow Runs, Deployments, Security Alerts und mehr.

Was du außerdem standardmäßig bekommst: das vollständige JSON-Schema jedes Tools wird beim Session-Start in den Kontext injiziert. Namen, Beschreibungen, Parametertypen, Enum-Werte, Beispiele — alles davon, bevor du auch nur einen einzigen Prompt getippt hast.

Wir haben im Laufe des Aufbaus von Statnive 24 MCP-Server angebunden. Über die Kosten haben wir erst nachgedacht, als sich unsere Sessions eng anfühlten. Dann haben wir zum ersten Mal /context ausgeführt.

Dieser Beitrag ist das Vorher/Nachher, das eine Flag, das 85 % der Arbeit erledigt hat, und die drei weiteren Muster, die den Rest übernommen haben.

Was uns /context gezeigt hat

Hier ist der relevante Ausschnitt unserer /context-Ausgabe vor jeder Optimierung:

MCP-Server	Tools	Verbrauchte Tokens
GitHub	35	~26.000
Slack	11	~21.000
Jira	~20	~17.000
Playwright (Browser-Automatisierung)	21	~13.647
Context7 (Library-Docs)	~15	~8.000
Weitere 19 Connector	~190	~50.000
MCP-Overhead gesamt	~290	~135.000

Das sind grob 67 % des gesamten 200K-Kontextfensters, ausgegeben für Tool-Definitionen für Tools, die wir in dieser Session vielleicht gar nicht nutzen. Das anderswo dokumentierte Muster bestätigt sich: Der durchschnittliche MCP-Tool-Overhead liegt bei ~500–710 Tokens pro Tool, und eine moderate Connector-Last (24 Server) verbraucht regelmäßig 48.000–120.000 Tokens, bevor irgendeine Arbeit beginnt. Der extremste dokumentierte Fall ist Dockers MCP-Server: 135 Tools, ~126.000 Tokens allein dafür.

Uns blieben ~65K Tokens für die eigentliche Konversation, den System-Prompt, eingebaute Tools, unsere CLAUDE.md, Skill-Metadaten und den Auto-Compact-Puffer. Deshalb fühlte sich alles eng an.

Tool Search: Das eine Flag, das 85 % der Arbeit erledigt hat

Claude Code v2.1.7 hat MCP Tool Search ausgeliefert. Statt jedes Tool-Schema beim Start zu injizieren, baut Tool Search einen leichtgewichtigen Index von etwa 5K Tokens auf, der nur Tool-Namen und -Beschreibungen enthält. Das vollständige Schema für ein einzelnes Tool wird erst geladen, wenn Claude tatsächlich entscheidet, es aufzurufen. Einmal geladen, bleibt es für die Session im Cache.

Anthropics interne Tests zeigten eine Reduktion von 134K auf ~5K Tokens — 85 % weniger. Kontraintuitiv: Die Genauigkeit in MCP-Evaluationen ging hoch, nicht runter: Opus 4 sprang im selben Benchmark von 49 % auf 74 %, vermutlich weil das Modell nicht in Tool-Schemas ertrank, die es gar nicht brauchte.

Tool Search aktiviert sich automatisch, sobald Tool-Beschreibungen ungefähr 10 % des Kontextfensters (~20K Tokens) überschreiten. Unterhalb dieser Schwelle bleibt es aus, mit der Annahme, dass du es nicht brauchst. Wir liegen deutlich darüber, also ist es bei uns immer aktiv.

Nach der Aktivierung sah unsere /context dramatisch anders aus:

Quelle	Vorher	Nachher
MCP-Tool-Schemas	~135.000	~3.000 (nur Index)
MCP-Tool-Schemas (während einer Session, die 4 Tools genutzt hat)	~135.000	~6.500 (Index + 4 geladene Schemas)
Verfügbarer Kontext für Arbeit	~65.000	~190.000

Verifizierungsschritt, den wir nie auslassen: /context beim Session-Start ausführen und die Zeile prüfen, in der steht, dass Tool-Schemas verzögert geladen werden oder dass Tool Search aktiv ist. Wenn nicht, zahlst du für nichts.

CRUD-Explosionen konsolidieren

Tool Search war der größte einzelne Hebel, aber es hilft nicht, wenn einzelne Tools aufgeblähte Beschreibungen haben oder deine Server Dutzende fast identische Tools bereitstellen.

Wir haben einen unserer internen MCP-Server nach einem in der Forschung dokumentierten Muster neu gebaut: Action-Parameter-Konsolidierung. Die ursprüngliche Zehn-Tool-API für Issue-Management:

create_issue, update_issue, delete_issue, list_issues, get_issue,
add_comment, update_comment, delete_comment, list_comments, get_comment

Wurde zu einem Tool:

manage_issues({ action: "create" | "update" | "delete" | "list" | "get",
                target: "issue" | "comment", ... })

Dokumentierte Ergebnisse eines Entwicklers, der dieses Muster angewendet hat: 20 Tools von 14.214 Tokens auf 5.663 Tokens — eine Reduktion um 60 %. Das Modell routet trotzdem korrekt, weil der Action-Parameter aufgezählt ist und die Tool-Beschreibung jede unterstützte Operation namentlich nennt. Wir haben bei unserer eigenen Konsolidierung ähnliche Ergebnisse gesehen: grob 9.800 Tokens auf 4.100.

Selbst wenn Tool Search Schema-Loads verzögert, ist der On-Demand-Load für ein dickes Tool deutlich kleiner als für zehn schlanke, weil Schema-Overhead von wiederholtem Boilerplate dominiert wird (Typdefinitionen, Error-Envelopes, Pagination-Muster).

Beschreibungen aggressiv kürzen

Die andere Seite derselben Medaille. Marketing-Prosa in Tool-Beschreibungen kostet echte Tokens.

Eine Beschreibung wie:

„Search the web using Tavily Search API. Best for factual queries requiring reliable sources and citations from authoritative web content. Handles complex topics with academic depth and provides comprehensive results with relevance scoring…”

Kostet 87 Tokens. Dasselbe Routing-Signal in:

„Search using Tavily. Best for factual/academic topics with citations.”

Kostet 12 Tokens. Über 290 Tools hinweg ergibt eine durchschnittliche Ersparnis von 50 Tokens pro Beschreibung ~14.500 Tokens.

Die Regel, die wir nutzen: Eine Beschreibung soll Claude helfen zu entscheiden, ob dieses Tool aufgerufen werden soll — nicht das Tool vermarkten. Streiche alles, was die Routing-Entscheidung nicht verändert.

Wann wir ein Tool eager geladen haben

Eine kleine Anzahl von Tools wollen wir eager laden, weil sie in fast jeder Session feuern:

• Read, Write, Edit, Grep, Glob, Bash — eingebaut, kein MCP, aber das Prinzip ist dasselbe: Hohe Aufruf-Frequenz rechtfertigt das Always-Loaded.
• Zwei MCP-Server, die wir mehrfach pro Session nutzen — unser internes Release-Tooling und unser Docs-Fetch-Server. Ihre Schemas summieren sich auf ~3.500 Tokens; sie 6+ Mal pro Session on-demand zu laden würde mehr Re-Fetch-Latenz kosten, als der Eager-Load einspart.

Tool Search unterstützt aus genau diesem Grund eine Per-Server-Eager-Allowlist. Setze sie chirurgisch ein — jedes Eager-Tool ist permanenter Overhead.

Output begrenzen, sonst begrenzt es dich

Die MCP-Umgebungsvariable MAX_MCP_OUTPUT_TOKENS steht standardmäßig auf 25.000 Tokens pro Tool-Antwort. Das ist großzügig für ein 200K-Fenster mit einem Tool-Aufruf pro Turn. Mit 24 Connectoren und Tools, die sich über mehrere Aufrufe pro Turn ausfächern, ist das ein garantierter Weg, den Kontext mit rohen API-Antworten zu fluten.

Wir haben unsere Grenze auf 4.000 gesetzt und von den output-lastigsten Servern verlangt, server-seitige Pagination und Summary-First-Response-Shapes zu unterstützen. Ein GitHub-list-issues-Aufruf gibt jetzt die ersten 20 zurück, mit einem has_more: true-Marker und einem Continuation-Token, statt 200 Issues in den Kontext zu kippen. Das Modell kann bei Bedarf nach mehr fragen; meistens tut es das nicht.

Für komplexe Multi-Tool-Workflows hat Programmatic Tool Calling (Claude schreibt Orchestrierungscode, der in einer sandboxed Umgebung läuft, wobei nur die finalen Ergebnisse in den Kontext kommen) in Anthropics internen Tests bei recherche-lastigen Aufgaben eine Reduktion um ~37 % Tokens gezeigt. Wir nutzen es für einen Workflow — einen Q&A-Agent, der 6 Doku-Server anspricht — und die Einsparungen halten.

CLI > MCP für selten genutzte Tools

Kontraintuitiv, aber real: Für Tools, die du selten nutzt, ist ein Shell-Befehl günstiger als ein MCP-Server. gh, aws, gcloud, sentry-cli, wp — sie laufen über das Bash-Tool mit null persistentem Kontext-Overhead. Die Beschreibung des Bash-Tools (bereits geladen) ist der gesamte Kontext, den du bezahlst. Der Hilfetext der CLI-Binary lädt nur, wenn Claude ihn liest.

Wir haben drei selten genutzte MCP-Server entfernt und durch CLI-Nutzung ersetzt. Allein das hat ~12.000 Tokens an Baseline-Overhead gespart.

Der Break-even-Punkt lautet ungefähr: Feuert dieses Tool mehr als einmal pro typischer Session? Wenn ja, MCP. Wenn nein, CLI.

Was wir nicht optimiert haben

• MAX_MCP_OUTPUT_TOKENS ist pro Aufruf, nicht pro Session. Ein sich daneben benehmender Server kann den Kontext über viele Turns hinweg trotzdem fluten. Per-Session-Caps haben wir noch nicht — das ist ein Feature-Request für Claude Code, nichts, was wir lokal fixen können.
• Tool Search ist an oder aus. Wir können MCP-Server nicht so tieren wie Skills. Alle 24 unserer Server gehen einheitlich durch Tool Search. Für einen Server, den wir in fast jeder Session nutzen, wäre Eager-Loading tatsächlich effizienter — aber wir können nicht selektiv nur die Schemas dieses einen Servers eager laden, ohne Tool Search global zu deaktivieren.
• Wir haben Routing-Genauigkeit auf unseren eigenen Workloads nicht sorgfältig gemessen. Anthropics 49 % → 74 % auf Opus 4 ist ermutigend, und in der Praxis haben wir keine Routing-Fehler gesehen, aber wir haben keine Benchmark-Suite, um zu beweisen, dass Deferred Loading für Statnive-spezifische Aufgaben genauso gut funktioniert wie Eager Loading.

Die praktischen Schritte, wenn du das heute machst

1. Führe /context in einer frischen Session aus. Schau, was tatsächlich geladen ist.
2. Wenn MCP-Tool-Schemas ~20K Tokens (10 % des Fensters) überschreiten, sollte Tool Search automatisch aktiv sein. Verifiziere das aus der /context-Ausgabe.
3. Auditiere deine drei schwersten Connector. Die Pareto-Kurve ist brutal — meist verbrauchen 3 Server 60 %+ des MCP-Overheads.
4. Konsolidiere CRUD-Explosionen in jedem MCP-Server, den du kontrollierst.
5. Kürze Beschreibungen jedes Tools, dessen Beschreibung sich liest wie Marketing-Copy.
6. Verschiebe selten genutzte Tools von MCP nach CLI.
7. Begrenze MAX_MCP_OUTPUT_TOKENS auf ein vernünftiges Per-Call-Limit (wir nutzen 4.000).

Wenn du das größere Bild willst — wie das mit CLAUDE.md-Optimierung und Skill-Tiering zusammenspielt, um multiplikative Einsparungen zu liefern — fang mit dem Flagship-Beitrag dieser Serie an.

Statnive ausprobieren

Datenschutzfreundliche WordPress-Analytics, ausgeliefert von einem Team, das darauf achtet, wohin jedes Token geht. Statnive kostenlos von WordPress.org installieren — deine Daten bleiben auf deinem Server.