Як зменшити витрату токенів на MCP: ми скоротили визначення інструментів на 60%

27 жовтня користувач, який платив, скасував підписку на AgentsRoom і назвав причиною токени. Перш ніж сперечатися з цим, ми виміряли, що наш застосунок додає до кожного агента, якого він запускає.

Найбільше число виявилося не там, де ми чекали. Наші стартові інструкції були невеликими. А інструменти MCP, які ми даємо кожному агенту (беклог, пам'ять проєкту, пошта між агентами, термінали, SSH, бази даних і все інше), це 191 інструмент і близько 380 КБ JSON. За приблизно 4 байти на токен це близько 95 000 токенів визначень інструментів. Тижнем раніше було 78 000. Ніхто цього не вирішував: кожен новий інструмент просто додавав свій абзац.

Ми робимо AgentsRoom, десктопний застосунок, який запускає Claude Code, Codex та інші CLI для програмування пліч-о-пліч і дає їм ці інструменти. Ось що ми виміряли, що скоротили, не прибравши жодного інструмента, і перевірка, яка не дає цьому повернутися. Усе це можна застосувати до твоїх власних серверів MCP.

Коротка відповідь

• Визначення інструмента це JSON, який модель може читати при кожному запиті: ім'я, опис, схема вхідних даних. Рахуй близько 4 байтів на токен.
• Чи платиш ти за нього на кожному ході, залежить від CLI. Claude Code за замовчуванням відкладає завантаження інструментів MCP і підвантажує визначення, коли воно потрібне. Деякі CLI надсилають усі схеми з кожним запитом.
• Спочатку виміряй, потім скорочуй. /context у Claude Code або скрипт на 40 рядків, який запитує в будь-якого сервера список інструментів.
• Скорочуй текст, зберігай інструменти. Опис каже, що і коли. Інструкція з використання переїжджає в документ, який агент читає на запит. Наші визначення зменшилися приблизно з 95 000 до приблизно 38 000 токенів, у 2,5 раза.
• Постав стелю в збірку. Без неї визначення знову розростаються самі собою.

Скільки коштує визначення інструмента і хто за нього платить

Коли клієнт MCP підключається до сервера, він запитує список інструментів. Кожен запис це ім'я, опис, написаний для моделі, і JSON-схема параметрів. Клієнт перетворює цей список на визначення інструментів, які надсилаються моделі: так модель дізнається, що інструмент існує і як його викликати.

Отже, кожне слово опису це вхід, який читає модель. Як часто вона його читає, залежить від клієнта:

• Claude Code за замовчуванням відкладає завантаження інструментів MCP. Його документація, прочитана 3 листопада 2026 року зі встановленим Claude Code 2.1.314, каже, що на початку сесії завантажуються лише імена інструментів та інструкції серверів, а визначення підвантажується через пошук інструментів, коли Claude потрібен цей інструмент. З ENABLE_TOOL_SEARCH=false, з auto нижче порогу в 10% контекстного вікна, на моделях, старіших за Claude Opus 4 і Sonnet 4, або для сервера з позначкою alwaysLoad визначення завантажуються одразу під час старту.
• Інші CLI поводяться інакше. У нашому власному тесті 28 жовтня агента просили відповісти «OK»: Claude Code стартував із 67 500 токенами при відкладених наших інструментах, Codex CLI 0.164 стартував із 25 000 токенами й не надсилав наші схеми одним блоком, а OpenCode під час підключення завантажував наші 175 інструментів плюс 19 інструментів браузера й надсилав їх із кожним запитом. Той самий сервер, зовсім різні рахунки.

Кешування промпту пом'якшує вартість, коли список інструментів не змінюється: після першого запиту стабільний префікс читається з кешу за частку ціни входу. Місця воно не повертає. Визначення все одно займають контекстне вікно при кожному запиті, поруч із твоїм кодом і твоєю розмовою. А відкладений режим має власну ціну: крок пошуку перед першим використанням кожного інструмента.

Виміряй свої за дві хвилини

У Claude Code запусти /context. Команда розкладає вікно за джерелами й позначає інструменти MCP, завантаження яких відкладене або відбувається на запит. Запусти її в новій сесії у своєму проєкті, перш ніж щось вводити, і побачиш, скільки коштує твоя конфігурація ще до початку роботи.

Для будь-якого сервера й будь-якого CLI запитай сервер напряму. Сервер MCP через stdio говорить JSON-RPC, одне повідомлення на рядок: ти надсилаєш initialize, потім tools/list і вимірюєш те, що повернулося. Цей скрипт робить саме це, на Node і без жодної залежності:

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

Запусти його з тією самою командою, якою твій CLI запускає сервер, наприклад node mcp-tool-cost.mjs npx -y @playwright/mcp@latest. Він виводить десять найважчих інструментів і підсумок. Ось що ми отримали 3 листопада 2026 року:

Чотири байти на токен це оцінка: її достатньо, щоб порівнювати сервери й бачити тенденцію, але не щоб передбачити рахунок. Справжні токенізатори залежать від моделі й тексту, як ми переконалися, коли порахували 3,8 мільярда власних токенів.

Файлові сервери вище цілком розумні. Проблема в сумі: п'ять серверів такого розміру це вже 20 000 токенів, ще до сервера на кшталт нашого.

Що ми скоротили і чого не чіпали

Правило, яке ми собі поставили: жодного видаленого інструмента, жодного видаленого параметра, жодного видаленого допустимого значення чи обов'язкового поля. Агенти мали зберегти всі можливості. Змінюватися міг лише текст.

1. Опис інструмента каже, що і коли, в одному-трьох реченнях. Не як. Саме в «як» і сиділи байти: правила, значення за замовчуванням, крайні випадки, приклади, попередження, написані після того, як агент одного разу неправильно використав інструмент.
2. Параметру достатньо одного речення або нічого, коли його ім'я, тип і список допустимих значень уже все кажуть. Параметри, що повторюються від інструмента до інструмента (project, author, ідентифікатори тікетів), отримали всюди одну й ту саму стандартну фразу.
3. Інструкція з використання переїхала, а не була видалена. Кожна родина інструментів має файл інструкцій, який агент читає перед першим викликом цієї родини. Для нашого найбільшого інструмента, того, що зберігає команду агентів, повний довідник полів тепер повертається викликом інструмента, коли агент його запитує, замість того щоб їхати всередині схеми.
4. Другий прохід перевірив кожен факт. Кожне речення, прибране з опису, шукали у файлах інструкцій і, якщо його там не було, повертали туди.

Деякі результати, у байтах JSON на інструмент:

Разом 380 КБ перетворилися на 152 КБ. Тринадцять інструментів були більшими за 4 КБ; чотири досі більші, через кількість полів, які вони несуть. Ідея всього проходу: щоб вибрати інструмент, моделі потрібно знати, що він існує і коли його викликати. Деталі можуть зачекати до моменту, коли вона його використовує.

Якщо ти пишеш сервер MCP, Claude Code дає ще одну причину. Він обрізає опис інструмента, завантажений одразу під час старту, на 4 096 символах, а коли зіставляє пошуковий запит з описом, читає лише частину в межах цього ліміту. Усе важливе після цієї межі може так і залишитися непрочитаним.

Той самий прийом для стартового файлу

Схеми інструментів не єдина постійна вартість. Наші агенти також читають файл інструкцій щодо інструментів, перш ніж ними користуватися, і він розрісся до 57,7 КБ, близько 14 000 токенів, які читалися повністю при кожному запуску і кожному відновленні. Користувач повідомив, що відновлений агент Codex упирався у свій ліміт робочого контексту за кілька хвилин.

Виправлення йшло за тією самою ідеєю. Файл став індексом приблизно на 11 КБ: правила, які діють для всіх інструментів, і по одному рядку на родину інструментів із посиланням на її власний файл. 31 файл родин читається лише перед першим викликом відповідної родини. Їхній текст не змінився, слово в слово. Агент, який працює лише з беклогом, ніколи не читає розділ про бази даних.

Це працює і для будь-якого довгого CLAUDE.md чи AGENTS.md: тримай у файлі, що завантажується завжди, те, що потрібно кожному завданню, а на решту став посилання. Докладніше ми писали про це в нашому посібнику щодо AGENTS.md і файлів контексту.

Бюджет, який провалює push

Найбільше нас турбувало не число 95 000. А 78 000 тижнем раніше. Кожен інструмент додавав абзац, кожен абзац був розумним, а сума зросла на 20% за сім днів.

Тому розмір став перевіркою в збірці. Бюджет зберігається в одному JSON-файлі:

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

Скрипт запускає наші сервери MCP у пісочниці, запитує в кожного його інструменти, вимірює JSON.stringify(tool) у байтах і завершується з помилкою, коли підсумок перевищує totalBytes або коли інструмент перевищує perToolBytes. Чотири інструменти, які вже були завеликими, перелічені зі своїм розміром: це храповик. Вони можуть зменшуватися, але не рости, а коли один із них зменшується, скрипт просить знизити число. Він запускається перед кожним push і в релізній збірці. Підняти стелю можна, але це рішення, записане у файлі, а не спосіб змусити перевірку пройти.

3 листопада, через шість днів, та сама перевірка показує 203 інструменти і 159 957 байтів: дванадцять інструментів додано, 43 байти нижче стелі. Наступному інструменту доведеться самому звільнити собі місце. Саме для цього перевірка й потрібна.

Вимкни те, чим не користуєшся

Найдешевший токен той, що належить інструменту, якого твій агент ніколи не бачить.

• Обмеж сервери проєктами, яким вони потрібні. Сервер, оголошений на рівні користувача, іде за тобою в кожен репозиторій. У Claude Code .mcp.json проєкту тримає його там, де він корисний.
• Залиш alwaysLoad для жмені інструментів. Документація Claude Code каже прямо: кожен інструмент, завантажений одразу під час старту, займає контекст, який інакше був би доступний для твоєї розмови.
• Стеж за тим, що додають результати інструментів, а не лише визначення. Інструмент, який повертає цілу сторінку чи таблицю, може коштувати за один виклик більше, ніж його визначення за весь день.

В AgentsRoom розділ Налаштування > Інструменти AgentsRoom показує кожну родину наших інструментів з її вагою, і ти можеш вимкнути родину або окремий інструмент для всіх проєктів, одного проєкту, папки чи одного агента. Вимкнений інструмент взагалі не показується агенту, тому не коштує жодного контексту. Сторінка AgentsRoom MCP описує інструменти, а трасування сесії показує, чим був заповнений контекст агента, включно з інструментами MCP, за спаданням розміру.

Що ми не змінювали

З того самого вимірювання вийшли ще дві статті витрат, і ми залишили їх як є, навмисно.

• Стартовий бриф, який повідомляє кожному агенту його роль і те, як звітувати про свій статус: медіана близько 5 000 токенів для Claude, приблизно 2,5% вікна у 200 000 токенів, і з другого запиту він читається з кешу.
• Файл статусу, який кожен агент пише наприкінці ходу: за вимірюванням на 71 локальному транскрипті Claude, близько 2,5% токенів контексту.

Скорочення будь-якого з них заощадило б менше ніж 3% вікна і поставило б під загрозу якість роботи агентів. Визначення інструментів важили 95 000 токенів. Туди й пішов час.

Запитання, які нам справді ставлять

Скільки токенів витрачають інструменти MCP?

Кожен інструмент коштує всього свого визначення: ім'я, опис і схема вхідних даних, надіслані у вигляді JSON. Грубе правило: 4 байти на токен. Вимірювання від 3 листопада 2026 року: офіційний сервер filesystem віддає 14 інструментів приблизно на 3 100 токенів, Playwright MCP 25 інструментів приблизно на 5 300. Інструменти AgentsRoom важили близько 95 000 токенів до того, як ми їх скоротили, сьогодні близько 40 000.

Чи завантажує Claude Code усі інструменти MCP у контекстне вікно?

Не за замовчуванням. Пошук інструментів Claude Code (tool search) відкладає завантаження визначень інструментів MCP: на початку сесії завантажуються лише імена інструментів та інструкції серверів, а визначення Claude підвантажує, коли йому потрібен цей інструмент. ENABLE_TOOL_SEARCH=false, модель, старіша за Claude Opus 4 і Sonnet 4, або сервер із позначкою alwaysLoad повертають визначення в контекст одразу під час старту.

Чи зменшують сервери MCP витрату токенів?

Можуть, коли інструмент повертає коротку відповідь замість того, що агент інакше прочитав би повністю, наприклад запит до бази даних замість повного дампу. Але визначення коштують контексту, і результати теж: Claude Code попереджає, коли один результат MCP перевищує 10 000 токенів, і за замовчуванням обрізає його на 25 000. Сервер MCP економить токени, лише якщо його результати менші за те, що він замінює.

Як подивитися, скільки контексту займають мої інструменти MCP?

У Claude Code запусти /context: команда розкладає контекст за джерелами й позначає відкладені інструменти MCP. Для будь-якого сервера й будь-якого CLI запитай у сервера список інструментів і виміряй JSON, саме це робить скрипт на 40 рядків із цієї статті.

Яким має бути хороший опис інструмента MCP?

Одне-три речення про те, що робить інструмент і коли його викликати, зі словами, які агент шукав би, ближче до початку. Параметру достатньо одного речення або нічого, якщо його ім'я, тип і допустимі значення вже все кажуть. Правила, крайні випадки й довгі приклади йдуть у документ, який агент читає на запит. До того ж Claude Code обрізає опис, завантажений одразу під час старту, на 4 096 символах.

Як не дати визначенням інструментів знову розростися?

Дай їм бюджет, який перевіряє збірка. У нас є JSON-файл із загальною стелею та стелею на один інструмент і скрипт, який запускає наші сервери MCP, вимірює кожен інструмент і завершується з помилкою, якщо перевищено будь-яку з меж, і ми запускаємо його перед кожним push. Інструменти, які вже були завеликими, можуть зменшуватися, але не рости.

Коротко

Твої інструменти MCP це текст, який читає модель, і ніхто не перевіряє цей текст так, як перевіряють код. Виміряй його один раз: /context у Claude Code або скрипт вище для будь-якого сервера. Потім зроби так, щоб кожен опис казав, що і коли, перенеси «як» у файл, який агент читає, коли йому потрібно, і постав число у свою збірку, щоб усе це не розповзлося назад.

Ми перейшли приблизно з 95 000 на приблизно 38 000 токенів, не прибравши жодного інструмента. Якщо ти запускаєш кількох агентів з однаковими інструментами, AgentsRoom можна завантажити безкоштовно, а сторінка серверів MCP показує, як оголосити сервер один раз для всіх CLI і проєктів.