Jak zmniejszyć zużycie tokenów przez MCP: skróciliśmy definicje naszych narzędzi o 60%

27 października płacący użytkownik anulował subskrypcję AgentsRoom i jako powód podał tokeny. Zanim zaczęliśmy z tym polemizować, zmierzyliśmy, co nasza aplikacja dokłada do każdego agenta, którego uruchamia.

Największa liczba nie była tam, gdzie się jej spodziewaliśmy. Nasze instrukcje startowe były małe. Narzędzia MCP, które dajemy każdemu agentowi (backlog, pamięć projektu, poczta między agentami, terminale, SSH, bazy danych i reszta), to było 191 narzędzi i około 380 KB JSON-a. Przy mniej więcej 4 bajtach na token daje to około 95 000 tokenów definicji narzędzi. Tydzień wcześniej było to 78 000. Nikt tak nie postanowił: każde nowe narzędzie po prostu dopisało swój akapit.

Tworzymy AgentsRoom, aplikację desktopową, która uruchamia Claude Code, Codex i inne CLI do kodowania obok siebie i daje im te narzędzia. Oto co zmierzyliśmy, co wycięliśmy bez usuwania choćby jednego narzędzia i jaka kontrola nie pozwala temu wrócić. Wszystko to możesz zastosować do własnych serwerów MCP.

Krótka odpowiedź

• Definicja narzędzia to JSON, który model może czytać przy każdym żądaniu: nazwa, opis, schemat wejścia. Licz około 4 bajtów na token.
• To, czy płacisz za to w każdej turze, zależy od CLI. Claude Code domyślnie ładuje narzędzia MCP z opóźnieniem i wczytuje definicję, gdy jej potrzebuje. Niektóre CLI wysyłają każdy schemat z każdym żądaniem.
• Zmierz, zanim zaczniesz ciąć. /context w Claude Code albo 40-liniowy skrypt, który pyta dowolny serwer o listę jego narzędzi.
• Skróć tekst, zachowaj narzędzia. Opis mówi co i kiedy. Instrukcja obsługi przenosi się do dokumentu, który agent czyta na żądanie. Nasze spadły z około 95 000 do około 38 000 tokenów, 2,5 raza mniej.
• Wpisz limit do builda. Bez niego definicje same znowu rosną.

Ile kosztuje definicja narzędzia i kto za nią płaci

Kiedy klient MCP łączy się z serwerem, prosi o listę narzędzi. Każdy wpis to nazwa, opis napisany dla modelu i schemat JSON parametrów. Klient zamienia tę listę w definicje narzędzi wysyłane do modelu: w ten sposób model wie, że narzędzie istnieje i jak je wywołać.

Każde słowo opisu to więc wejście, które model czyta. Jak często je czyta, zależy od klienta:

• Claude Code domyślnie ładuje narzędzia MCP z opóźnieniem. Jego dokumentacja, przeczytana 3 listopada 2026 przy zainstalowanym Claude Code 2.1.314, mówi, że na starcie sesji ładują się tylko nazwy narzędzi i instrukcje serwerów, a definicja jest wczytywana przez wyszukiwanie narzędzi, gdy Claude potrzebuje danego narzędzia. Przy ENABLE_TOOL_SEARCH=false, przy auto poniżej progu 10% okna kontekstu, na modelach starszych niż Claude Opus 4 i Sonnet 4 albo dla serwera oznaczonego jako alwaysLoad definicje ładują się od samego początku.
• Inne CLI robią to inaczej. W naszym własnym teście z 28 października, z agentem, który miał odpowiedzieć tylko „OK”: Claude Code startował z 67 500 tokenami przy naszych narzędziach ładowanych z opóźnieniem, Codex CLI 0.164 startował z 25 000 tokenami i nie wysyłał naszych schematów jednym blokiem, a OpenCode ładował nasze 175 narzędzi plus 19 narzędzi przeglądarki przy połączeniu i wysyłał je z każdym żądaniem. Ten sam serwer, bardzo różne rachunki.

Cache promptów łagodzi koszt, gdy lista narzędzi się nie zmienia: po pierwszym żądaniu stabilny prefiks jest czytany z cache za ułamek ceny wejścia. Nie oddaje jednak miejsca. Definicje nadal siedzą w oknie kontekstu przy każdym żądaniu, obok twojego kodu i twojej rozmowy. A tryb z opóźnionym ładowaniem ma własny koszt: krok wyszukiwania przed pierwszym użyciem każdego narzędzia.

Zmierz swoje w dwie minuty

W Claude Code uruchom /context. Rozbija okno według źródła i oznacza narzędzia MCP ładowane z opóźnieniem albo na żądanie. Uruchom go w świeżej sesji w swoim projekcie, zanim cokolwiek wpiszesz, a zobaczysz, ile kosztuje twoja konfiguracja, zanim zacznie się praca.

Dla dowolnego serwera i dowolnego CLI zapytaj serwer bezpośrednio. Serwer MCP przez stdio mówi JSON-RPC, jedna wiadomość na linię: wysyłasz initialize, potem tools/list, i mierzysz to, co wraca. Ten skrypt robi dokładnie to, w Node i bez żadnych zależności:

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

Uruchom go tym samym poleceniem, którym twoje CLI uruchamia serwer, na przykład node mcp-tool-cost.mjs npx -y @playwright/mcp@latest. Wypisuje dziesięć najcięższych narzędzi i sumę. Oto co dostaliśmy 3 listopada 2026:

Cztery bajty na token to szacunek, wystarczający, żeby porównać serwery i zobaczyć trend, ale nie żeby przewidzieć rachunek. Prawdziwe tokenizery różnią się w zależności od modelu i tekstu, o czym przekonaliśmy się, gdy policzyliśmy 3,8 miliarda naszych własnych tokenów.

Powyższe serwery plików są rozsądne. Problemem jest suma: pięć serwerów tej wielkości to już 20 000 tokenów, jeszcze przed serwerem takim jak nasz.

Co wycięliśmy, a czego nie ruszaliśmy

Zasada, którą sobie postawiliśmy: żadne narzędzie nie usunięte, żaden parametr nie usunięty, żadna dozwolona wartość ani wymagane pole nie usunięte. Agenci mieli zachować wszystkie możliwości. Zmieniać mógł się tylko tekst.

1. Opis narzędzia mówi co i kiedy, w jednym do trzech zdań. Nie jak. To w „jak” siedziały bajty: reguły, wartości domyślne, przypadki brzegowe, przykłady, ostrzeżenia dopisane po tym, jak agent raz źle użył narzędzia.
2. Parametr dostaje jedno zdanie albo nic, gdy jego nazwa, typ i lista dozwolonych wartości już mówią wszystko. Parametry powtarzające się w wielu narzędziach (project, author, identyfikatory zgłoszeń) dostały wszędzie to samo standardowe zdanie.
3. Instrukcja obsługi się przeniosła, nie została usunięta. Każda rodzina narzędzi ma plik instrukcji, który agent czyta przed pierwszym wywołaniem tej rodziny. Dla naszego największego narzędzia, tego, które zapisuje zespół agentów, pełny opis pól zwraca teraz wywołanie narzędzia, gdy agent o to poprosi, zamiast jechać w schemacie.
4. Druga runda sprawdziła każdy fakt. Każde zdanie usunięte z opisu zostało odszukane w plikach instrukcji i dopisane tam, jeśli go brakowało.

Część wyników, w bajtach JSON-a na narzędzie:

W sumie 380 KB zmieniło się w 152 KB. Trzynaście narzędzi przekraczało 4 KB; cztery nadal przekraczają, z powodu liczby pól, które niosą. Idea całej rundy: żeby wybrać narzędzie, model musi wiedzieć, że ono istnieje i kiedy je wywołać. Szczegóły mogą poczekać do chwili, w której go używa.

Jeśli piszesz serwer MCP, Claude Code daje ci jeszcze jeden powód. Ucina opis narzędzia ładowany od początku na 4 096 znakach, a gdy dopasowuje wyszukiwanie do opisu, czyta tylko część mieszczącą się w tym limicie. Wszystko, co ważne, a leży za tym punktem, może nigdy nie zostać zauważone.

Ten sam trik dla pliku startowego

Schematy narzędzi nie są jedynym stałym kosztem. Nasi agenci czytają też plik instrukcji o narzędziach, zanim ich użyją, i urósł on do 57,7 KB, około 14 000 tokenów, czytanych w całości przy każdym starcie i każdym wznowieniu. Użytkownik zgłosił, że wznowiony agent Codex w ciągu kilku minut dochodził do limitu swojego kontekstu roboczego.

Poprawka poszła tym samym tropem. Plik stał się indeksem o wielkości około 11 KB: reguły, które dotyczą każdego narzędzia, i jedna linia na rodzinę narzędzi, wskazująca jej własny plik. 31 plików rodzin jest czytanych dopiero przed pierwszym wywołaniem danej rodziny. Ich tekst się nie zmienił, słowo w słowo. Agent, który dotyka tylko backlogu, nigdy nie czyta sekcji o bazach danych.

To działa też dla każdego długiego CLAUDE.md czy AGENTS.md: trzymaj w zawsze ładowanym pliku to, czego potrzebuje każde zadanie, a do reszty daj link. Więcej o tym piszemy w naszym przewodniku po AGENTS.md i plikach kontekstu.

Budżet, który blokuje push

Liczba, która martwiła nas najbardziej, to nie było 95 000. To było 78 000 tydzień wcześniej. Każde narzędzie dodawało akapit, każdy akapit był rozsądny, a suma urosła o 20% w siedem dni.

Rozmiar stał się więc kontrolą w buildzie. Jeden plik JSON przechowuje budżet:

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

Skrypt uruchamia nasze serwery MCP w sandboksie, pyta każdy o jego narzędzia, mierzy JSON.stringify(tool) w bajtach i kończy się błędem, gdy suma przekracza totalBytes albo gdy któreś narzędzie przekracza perToolBytes. Cztery narzędzia, które już były za duże, są wypisane razem z rozmiarem: działa to jak zapadka. Mogą się zmniejszać, nigdy rosnąć, a gdy któreś się zmniejszy, skrypt prosi o obniżenie liczby. Działa przed każdym pushem i w buildzie wydania. Podniesienie limitu jest możliwe, ale to decyzja zapisana w pliku, a nie sposób, żeby kontrola przeszła.

3 listopada, sześć dni później, ta sama kontrola odczytuje 203 narzędzia i 159 957 bajtów: dwanaście nowych narzędzi, 43 bajty poniżej limitu. Następne narzędzie będzie musiało samo zrobić sobie miejsce. Dokładnie do tego służy ta kontrola.

Wyłącz to, czego nie używasz

Najtańszy token to token narzędzia, którego twój agent nigdy nie widzi.

• Ogranicz serwery do projektów, które ich potrzebują. Serwer zadeklarowany na poziomie użytkownika idzie za tobą do każdego repozytorium. W Claude Code plik .mcp.json projektu trzyma go tam, gdzie jest przydatny.
• Zostaw alwaysLoad dla garstki narzędzi. Dokumentacja Claude Code mówi to wprost: każde narzędzie ładowane od początku zużywa kontekst, który inaczej byłby dostępny dla twojej rozmowy.
• Pilnuj tego, co dokładają wyniki narzędzi, nie tylko definicje. Narzędzie, które zwraca całą stronę albo tabelę, może w jednym wywołaniu kosztować więcej niż jego definicja przez cały dzień.

W AgentsRoom Ustawienia > Narzędzia AgentsRoom pokazują każdą rodzinę naszych narzędzi z jej wagą, a ty możesz wyłączyć rodzinę albo pojedyncze narzędzie, dla wszystkich projektów, jednego projektu, folderu albo jednego agenta. Wyłączone narzędzie w ogóle nie jest pokazywane agentowi, więc nie kosztuje żadnego kontekstu. Strona AgentsRoom MCP opisuje narzędzia, a ślad sesji pokazuje, co wypełniło kontekst agenta, łącznie z narzędziami MCP, uszeregowane według rozmiaru.

Czego nie zmieniliśmy

Z tego samego pomiaru wyszły dwa inne koszty i celowo zostawiliśmy je w spokoju.

• Brief startowy, który mówi każdemu agentowi, jaka jest jego rola i jak ma zgłaszać swój status: mediana około 5 000 tokenów dla Claude, około 2,5% okna 200 000 tokenów, a od drugiego żądania czytany z cache.
• Plik statusu, który każdy agent zapisuje na koniec tury: zmierzony na 71 lokalnych transkryptach Claude, około 2,5% tokenów kontekstu.

Zmniejszenie któregokolwiek z nich oszczędziłoby mniej niż 3% okna, a naraziłoby jakość pracy agentów. Definicje narzędzi to było 95 000 tokenów. Tam poszedł nasz czas.

Pytania, które ludzie naprawdę zadają

Ile tokenów zużywają narzędzia MCP?

Każde narzędzie kosztuje całą swoją definicję: nazwę, opis i schemat wejścia, wysyłane jako JSON. Z grubsza można liczyć 4 bajty na token. Pomiar z 3 listopada 2026: oficjalny serwer filesystem udostępnia 14 narzędzi za około 3 100 tokenów, Playwright MCP 25 narzędzi za około 5 300. Narzędzia AgentsRoom ważyły około 95 000 tokenów, zanim je skróciliśmy, dziś około 40 000.

Czy Claude Code ładuje każde narzędzie MCP do okna kontekstu?

Nie domyślnie. Wyszukiwanie narzędzi w Claude Code (tool search) odkłada definicje narzędzi MCP na później: na starcie sesji ładują się tylko nazwy narzędzi i instrukcje serwerów, a Claude ładuje definicję, gdy potrzebuje danego narzędzia. Ustawienie ENABLE_TOOL_SEARCH=false, model starszy niż Claude Opus 4 i Sonnet 4 albo serwer oznaczony jako alwaysLoad sprawiają, że definicje znowu trafiają do kontekstu od samego początku.

Czy serwery MCP zmniejszają zużycie tokenów?

Mogą, gdy narzędzie zwraca krótką odpowiedź zamiast czegoś, co agent musiałby inaczej przeczytać w całości, na przykład zapytanie do bazy danych zamiast pełnego zrzutu. Ale definicje kosztują kontekst, wyniki też: Claude Code ostrzega, gdy pojedynczy wynik MCP przekracza 10 000 tokenów, i domyślnie ucina go na 25 000. Serwer MCP oszczędza tokeny tylko wtedy, gdy jego wyniki są mniejsze niż to, co zastępuje.

Jak sprawdzić, ile kontekstu zajmują moje narzędzia MCP?

W Claude Code uruchom /context: rozbija kontekst według źródła i oznacza narzędzia MCP ładowane z opóźnieniem. Dla dowolnego serwera i dowolnego CLI poproś serwer o listę jego narzędzi i zmierz JSON, a to właśnie robi 40-liniowy skrypt z tego artykułu.

Jak wygląda dobry opis narzędzia MCP?

Od jednego do trzech zdań, które mówią, co narzędzie robi i kiedy je wywołać, ze słowami, których agent by szukał, blisko początku. Parametr dostaje jedno zdanie albo nic, gdy jego nazwa, typ i dozwolone wartości już to mówią. Reguły, przypadki brzegowe i długie przykłady trafiają do dokumentu, który agent czyta na żądanie. Claude Code i tak ucina opis ładowany od początku na 4 096 znakach.

Jak sprawić, żeby definicje narzędzi znowu nie rosły?

Daj im budżet, który build może sprawdzić. Trzymamy plik JSON z limitem całkowitym i limitem na narzędzie, skrypt, który uruchamia nasze serwery MCP, mierzy każde narzędzie i kończy się błędem powyżej któregokolwiek limitu, i uruchamiamy go przed każdym pushem. Narzędzia, które już były za duże, mogą się zmniejszać, nigdy rosnąć.

Wersja skrócona

Twoje narzędzia MCP to tekst, który czyta model, a nikt nie przegląda tego tekstu tak, jak przegląda się kod. Zmierz go raz: /context w Claude Code albo powyższy skrypt dla dowolnego serwera. Potem niech każdy opis mówi co i kiedy, przenieś „jak” do pliku, który agent czyta, gdy go potrzebuje, i wpisz liczbę do swojego builda, żeby nic nie mogło się z powrotem rozrosnąć.

Zeszliśmy z około 95 000 do około 38 000 tokenów bez usuwania żadnego narzędzia. Jeśli uruchamiasz kilku agentów z tymi samymi narzędziami, AgentsRoom można pobrać za darmo, a strona o serwerach MCP pokazuje, jak zadeklarować serwer raz dla każdego CLI i każdego projektu.