MCP token kullanımını azaltmak: araç tanımlarımızı nasıl %60 küçülttük

27 Ekim'de ücretli bir kullanıcı AgentsRoom aboneliğini iptal etti ve sebep olarak token'ları gösterdi. Buna itiraz etmeden önce, uygulamamızın başlattığı her ajana neler eklediğini ölçtük.

En büyük sayı beklediğimiz yerde değildi. Başlangıç talimatlarımız küçüktü. Her ajana verdiğimiz MCP araçları (backlog, proje hafızası, ajanlar arası posta, terminaller, SSH, veritabanları ve geri kalanı) ise 191 araç ve yaklaşık 380 KB JSON'du. Token başına kabaca 4 baytla bu, yaklaşık 95.000 token'lık araç tanımı demek. Bir hafta önce 78.000'di. Bunu kimse kararlaştırmamıştı; her yeni araç sadece kendi paragrafını eklemişti.

AgentsRoom bizim geliştirdiğimiz bir masaüstü uygulaması: Claude Code, Codex ve diğer kodlama CLI'lerini yan yana çalıştırıyor ve onlara bu araçları veriyor. İşte ölçtüklerimiz, tek bir araç kaldırmadan kestiklerimiz ve bunun geri gelmesini engelleyen kontrol. Bunların hepsini kendi MCP sunucularına uygulayabilirsin.

Kısa cevap

• Bir araç tanımı, modelin her istekte okuyabileceği JSON'dur: ad, açıklama, girdi şeması. Token başına yaklaşık 4 bayt say.
• Bunu her turda ödeyip ödemediğin CLI'ye bağlı. Claude Code MCP araçlarını varsayılan olarak erteler ve bir tanıma ihtiyaç duyduğunda onu yükler. Bazı CLI'ler her istekle tüm şemaları gönderir.
• Kesmeden önce ölç. Claude Code'da /context ya da herhangi bir sunucudan araç listesini isteyen 40 satırlık bir betik.
• Metni kısalt, araçları koru. Bir açıklama ne ve ne zaman olduğunu söyler. Kullanım kılavuzu, ajanın gerektiğinde okuduğu bir belgeye taşınır. Bizimkiler yaklaşık 95.000'den yaklaşık 38.000 token'a indi, 2,5 kat daha az.
• Build'e bir tavan koy. Tavan olmadan tanımlar kendiliğinden yeniden şişer.

Bir araç tanımının maliyeti ve bunu kimin ödediği

Bir MCP istemcisi bir sunucuya bağlandığında araç listesini ister. Her kayıt bir ad, model için yazılmış bir açıklama ve parametrelerin JSON şemasıdır. İstemci bu listeyi modele gönderilen araç tanımlarına dönüştürür: model, aracın var olduğunu ve onu nasıl çağıracağını bu şekilde öğrenir.

Yani bir açıklamanın her kelimesi modelin okuduğu girdidir. Bunu ne sıklıkla okuduğu istemciye bağlıdır:

• Claude Code MCP araçlarını varsayılan olarak erteler. 3 Kasım 2026'da Claude Code 2.1.314 kuruluyken okunan belgeleri, oturum başında yalnızca araç adlarının ve sunucu talimatlarının yüklendiğini, bir tanımın ise Claude o araca ihtiyaç duyduğunda araç aramasıyla yüklendiğini söylüyor. ENABLE_TOOL_SEARCH=false ile, bağlam penceresinin %10'luk eşiğinin altında auto ile, Claude Opus 4 ve Sonnet 4'ten eski modellerde ya da alwaysLoad olarak işaretlenmiş bir sunucu için tanımlar en baştan yüklenir.
• Diğer CLI'ler farklı davranır. 28 Ekim'deki kendi testimizde bir ajandan "OK" diye cevap vermesini istedik: Claude Code araçlarımız ertelenmiş halde 67.500 token'la açıldı, Codex CLI 0.164 25.000 token'la açıldı ve şemalarımızı tek blok halinde göndermedi, OpenCode ise bağlantı anında 175 aracımızı ve 19 tarayıcı aracını yükleyip bunları her istekle gönderdi. Aynı sunucu, çok farklı faturalar.

Prompt önbelleği, araç listesi değişmediğinde maliyeti yumuşatır: ilk istekten sonra sabit bir önek, girdi fiyatının küçük bir kesrine önbellekten okunur. Ama yeri geri vermez. Tanımlar her istekte bağlam penceresinde, kodunun ve konuşmanın yanında durmaya devam eder. Ertelenmiş modun da kendi maliyeti vardır: her aracın ilk kullanımından önce bir arama adımı.

Kendininkini iki dakikada ölç

Claude Code'da /context komutunu çalıştır. Pencereyi kaynağa göre ayırır ve ertelenmiş ya da talep üzerine yüklenen MCP araçlarını işaretler. Bunu projende yeni bir oturumda, hiçbir şey yazmadan önce çalıştır; böylece iş başlamadan önce kurulumunun neye mal olduğunu görürsün.

Herhangi bir sunucu ve herhangi bir CLI için doğrudan sunucuya sor. stdio üzerinden çalışan bir MCP sunucusu JSON-RPC konuşur, satır başına bir mesaj: initialize, ardından tools/list gönderirsin ve dönen şeyi ölçersin. Bu betik tam olarak bunu yapar, Node ile ve hiçbir bağımlılık olmadan:

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

Betiği, CLI'nin sunucuyu başlatmak için kullandığı komutla çalıştır, örneğin node mcp-tool-cost.mjs npx -y @playwright/mcp@latest. En ağır on aracı ve toplamı yazdırır. 3 Kasım 2026'da elde ettiğimiz sonuç:

Token başına dört bayt bir tahmindir: sunucuları karşılaştırmak ve bir eğilimi görmek için yeterli, bir faturayı öngörmek için değil. Gerçek tokenizer'lar modele ve metne göre değişir; bunu kendi 3,8 milyar token'ımızı saydığımızda gördük.

Yukarıdaki dosya sunucuları makul. Sorun toplamda: bu boyutta beş sunucu, bizimki gibi bir sunucu daha gelmeden 20.000 token ediyor.

Neleri kestik, neye dokunmadık

Koyduğumuz kural: hiçbir araç kaldırılmayacak, hiçbir parametre kaldırılmayacak, hiçbir izin verilen değer ya da zorunlu alan kaldırılmayacak. Ajanlar tüm yeteneklerini korumalıydı. Yalnızca metin değişebilirdi.

1. Bir araç açıklaması bir ila üç cümlede ne ve ne zaman olduğunu söyler. Nasıl olduğunu değil. Baytlar tam da "nasıl" kısmındaydı: kurallar, varsayılanlar, uç durumlar, örnekler, bir ajan aracı bir kez yanlış kullandıktan sonra yazılmış uyarılar.
2. Bir parametreye tek cümle yeter, ya da hiçbir şey, eğer adı, türü ve izin verilen değerler listesi zaten her şeyi söylüyorsa. Araçtan araca tekrarlanan parametreler (project, author, ticket kimlikleri) her yerde aynı standart cümleyi aldı.
3. Kullanım kılavuzu taşındı, silinmedi. Her araç ailesinin, ajanın o aileye ilk çağrısından önce okuduğu bir talimat dosyası var. En büyük aracımız için, yani bir ajan ekibini kaydeden araç için, alanların tam başvuru kaynağı artık şemanın içinde taşınmak yerine ajan istediğinde bir araç çağrısıyla döndürülüyor.
4. İkinci bir geçiş her bilgiyi doğruladı. Bir açıklamadan çıkarılan her cümle talimat dosyalarında arandı ve eksikse oraya geri kondu.

Sonuçlardan bazıları, araç başına JSON baytı olarak:

Toplamda 380 KB, 152 KB'a indi. On üç araç 4 KB'ın üzerindeydi; dördü taşıdıkları alan sayısı yüzünden hâlâ öyle. Tüm geçişin arkasındaki fikir: bir aracı seçmek için modelin, aracın var olduğunu ve onu ne zaman çağıracağını bilmesi gerekir. Ayrıntılar, onu kullanacağı ana kadar bekleyebilir.

Bir MCP sunucusu yazıyorsan, Claude Code sana bir sebep daha veriyor. En baştan yüklenen bir araç açıklamasını 4.096 karakterde keser ve bir aramayı bir açıklamayla eşleştirirken yalnızca bu sınırın içindeki kısmı okur. O noktadan sonraki önemli her şey hiç görülmeyebilir.

Bir başlangıç dosyası için aynı yöntem

Araç şemaları tek sabit maliyet değil. Ajanlarımız araçları kullanmadan önce onlarla ilgili bir talimat dosyası da okuyor ve bu dosya 57,7 KB'a, yaklaşık 14.000 token'a çıkmıştı; her başlangıçta ve her devam ettirmede baştan sona okunuyordu. Bir kullanıcı, devam ettirilen bir Codex ajanının birkaç dakika içinde çalışma bağlamı sınırına ulaştığını bildirdi.

Çözüm aynı fikri izledi. Dosya yaklaşık 11 KB'lık bir dizine dönüştü: her araç için geçerli kurallar ve her araç ailesi için kendi dosyasına işaret eden bir satır. 31 aile dosyası yalnızca o aileye yapılan ilk çağrıdan önce okunuyor. Metinleri kelimesi kelimesine değişmedi. Yalnızca backlog'a dokunan bir ajan veritabanlarıyla ilgili bölümü hiç okumaz.

Bu, uzun bir CLAUDE.md ya da AGENTS.md için de işe yarar: her zaman yüklenen dosyada her görevin ihtiyaç duyduğunu tut, gerisine bağlantı ver. Bunu AGENTS.md ve bağlam dosyaları rehberimizde daha ayrıntılı anlattık.

Push'u başarısız kılan bir bütçe

Bizi en çok endişelendiren sayı 95.000 değildi. Bir hafta önceki 78.000'di. Her araç bir paragraf ekledi, her paragraf makuldü ve toplam yedi günde %20 büyüdü.

Bu yüzden boyut bir build kontrolüne dönüştü. Bütçeyi tek bir JSON dosyası tutuyor:

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

Bir betik MCP sunucularımızı bir sandbox içinde başlatır, her birinden araçlarını ister, JSON.stringify(tool) değerini bayt olarak ölçer ve toplam totalBytes değerini ya da bir araç perToolBytes değerini aştığında hatayla çıkar. Zaten fazla büyük olan dört araç boyutlarıyla birlikte listelenir: bir cırcır mekanizması. Küçülebilirler, asla büyüyemezler; biri küçüldüğünde betik sayının düşürülmesini ister. Her push öncesinde ve release build'inde çalışır. Tavanı yükseltmek mümkün, ama bu dosyaya yazılmış bir karardır, kontrolü geçirmenin bir yolu değil.

3 Kasım'da, altı gün sonra, aynı kontrol 203 araç ve 159.957 bayt okuyor: on iki araç eklendi, tavanın 43 bayt altında. Bir sonraki araç kendine yer açmak zorunda kalacak. Kontrol tam olarak bunun için var.

Kullanmadığını kapat

En ucuz token, ajanının hiç görmediği araca ait olandır.

• Sunucuları ihtiyaç duyan projelerle sınırla. Kullanıcı düzeyinde tanımlanan bir sunucu seni her depoya takip eder. Claude Code'da bir projenin .mcp.json dosyası onu işe yaradığı yerde tutar.
• alwaysLoad ayarını bir avuç araca sakla. Claude Code belgeleri bunu açıkça söylüyor: en baştan yüklenen her araç, aksi halde konuşman için kullanılabilecek bağlamı tüketir.
• Yalnızca tanımları değil, araç sonuçlarının ne eklediğini de izle. Bütün bir sayfa ya da tablo döndüren bir araç, tek bir çağrıda, tanımının bütün gün boyunca tuttuğundan fazlasına mal olabilir.

AgentsRoom'da Ayarlar > AgentsRoom araçları, araçlarımızın her ailesini ağırlığıyla listeler ve bir aileyi ya da tek bir aracı tüm projeler, tek bir proje, bir klasör ya da tek bir ajan için kapatabilirsin. Kapatılan bir araç ajana hiç listelenmez, dolayısıyla hiç bağlam tüketmez. AgentsRoom MCP sayfası araçları anlatıyor, oturum izi ise bir ajanın bağlamını neyin doldurduğunu, MCP araçları dahil, boyuta göre sıralı olarak gösteriyor.

Neyi değiştirmedik

Aynı ölçümden iki maliyet daha çıktı ve onlara bilerek dokunmadık.

• Başlangıç brifi: her ajana rolünü ve durumunu nasıl bildireceğini söyler. Claude için medyan yaklaşık 5.000 token, 200.000 token'lık bir pencerenin yaklaşık %2,5'i ve ikinci istekten itibaren önbellekten okunuyor.
• Her ajanın bir turun sonunda yazdığı durum dosyası: 71 yerel Claude transkripti üzerinde ölçüldü, bağlam token'larının yaklaşık %2,5'i.

Bunlardan birini küçültmek pencerenin %3'ünden azını kazandırır ve ajanların işinin kalitesini riske atardı. Araç tanımları 95.000 token tutuyordu. Zaman oraya gitti.

İnsanların gerçekten sorduğu sorular

MCP araçları kaç token kullanır?

Her araç, tanımının tamamı kadar tutar: ad, açıklama ve girdi şeması, JSON olarak gönderilir. Kabaca kural, token başına 4 bayttır. 3 Kasım 2026'da ölçüldü: resmi filesystem sunucusu yaklaşık 3.100 token için 14 araç listeliyor, Playwright MCP yaklaşık 5.300 token için 25 araç. AgentsRoom araçları biz kısaltmadan önce yaklaşık 95.000 token tutuyordu, bugün yaklaşık 40.000.

Claude Code her MCP aracını bağlam penceresine yükler mi?

Varsayılan olarak hayır. Claude Code'un araç araması (tool search) MCP araç tanımlarını erteler: oturum başında yalnızca araç adları ve sunucu talimatları yüklenir, Claude bir tanımı o araca ihtiyaç duyduğunda yükler. ENABLE_TOOL_SEARCH=false ayarı, Claude Opus 4 ve Sonnet 4'ten eski bir model ya da alwaysLoad olarak işaretlenmiş bir sunucu, tanımları en baştan bağlama geri koyar.

MCP sunucuları token kullanımını azaltır mı?

Azaltabilir: bir araç, ajanın aksi halde baştan sona okuyacağı bir şeyin yerine kısa bir yanıt döndürdüğünde, örneğin tam bir döküm yerine bir veritabanı sorgusu. Ama tanımlar bağlamdan yer tutar, sonuçlar da öyle: Claude Code tek bir MCP sonucu 10.000 token'ı geçtiğinde uyarır ve varsayılan olarak 25.000'de keser. Bir MCP sunucusu ancak sonuçları yerini aldığı şeyden küçükse token tasarrufu sağlar.

MCP araçlarımın ne kadar bağlam kapladığını nasıl görürüm?

Claude Code'da /context komutunu çalıştır: bağlamı kaynağa göre ayırır ve ertelenmiş MCP araçlarını işaretler. Herhangi bir sunucu ve herhangi bir CLI için sunucudan araç listesini iste ve JSON'u ölç; bu yazıdaki 40 satırlık betiğin yaptığı tam olarak bu.

İyi bir MCP araç açıklaması nasıl olur?

Aracın ne yaptığını ve ne zaman çağrılacağını söyleyen bir ila üç cümle; bir ajanın arayacağı kelimeler başa yakın olsun. Bir parametreye tek cümle yeter, adı, türü ve izin verilen değerleri zaten her şeyi söylüyorsa hiçbir şey. Kurallar, uç durumlar ve uzun örnekler, ajanın gerektiğinde okuduğu bir belgeye gider. Zaten Claude Code, en baştan yüklenen bir açıklamayı 4.096 karakterde keser.

Araç tanımlarının yeniden şişmesini nasıl önlerim?

Onlara build'in kontrol edebileceği bir bütçe ver. Bizde toplam bir tavan ve araç başına bir tavan içeren bir JSON dosyası, MCP sunucularımızı başlatıp her aracı ölçen ve iki sınırdan biri aşıldığında hatayla çıkan bir betik var; bunu her push öncesinde çalıştırıyoruz. Zaten fazla büyük olan araçlar küçülebilir, asla büyüyemez.

Kısacası

MCP araçların modelin okuduğu metindir ve kimse bu metni kodu gözden geçirdiği gibi gözden geçirmez. Bir kez ölç: Claude Code'da /context ya da herhangi bir sunucu için yukarıdaki betik. Sonra her açıklamanın ne ve ne zaman olduğunu söylemesini sağla, "nasıl" kısmını ajanın ihtiyaç duyduğunda okuduğu bir dosyaya taşı ve build'ine bir sayı koy ki geri kaymasın.

Hiçbir aracı kaldırmadan yaklaşık 95.000'den yaklaşık 38.000 token'a indik. Aynı araçlarla birkaç ajan çalıştırıyorsan AgentsRoom ücretsiz indirilebilir ve MCP sunucuları sayfası bir sunucuyu her CLI ve proje için bir kez nasıl tanımlayacağını gösteriyor.