MCP 토큰 사용량 줄이기: 도구 정의를 60% 줄인 방법

10월 27일, 유료 사용자 한 명이 AgentsRoom 구독을 해지하면서 토큰을 이유로 들었습니다. 반박하기 전에, 저희 앱이 띄우는 에이전트마다 무엇을 얹고 있는지부터 측정했습니다.

가장 큰 숫자는 예상한 곳에 있지 않았습니다. 시작 지침은 작았습니다. 모든 에이전트에 건네는 MCP 도구(백로그, 프로젝트 메모리, 에이전트 메일, 터미널, SSH, 데이터베이스 등)는 191개, JSON으로 약 380 KB였습니다. 4바이트당 약 1토큰으로 치면 도구 정의만 약 95,000토큰입니다. 일주일 전에는 78,000이었습니다. 누가 그렇게 정한 것이 아닙니다. 새 도구가 생길 때마다 각자 자기 문단을 보탰을 뿐입니다.

저희가 만드는 AgentsRoom은 Claude Code, Codex 같은 코딩 CLI를 나란히 실행하고 이 도구들을 쥐여 주는 데스크톱 앱입니다. 여기서는 저희가 측정한 것, 도구를 하나도 없애지 않고 줄인 것, 그리고 그것이 되돌아오지 않게 막는 검사를 소개합니다. 모두 여러분의 MCP 서버에 그대로 적용할 수 있습니다.

짧은 답

• 도구 정의는 모델이 요청마다 읽을 수 있는 JSON입니다: 이름, 설명, 입력 스키마. 대략 4바이트당 1토큰으로 계산하세요.
• 매 턴마다 그 비용을 내는지는 CLI에 달려 있습니다. Claude Code는 기본적으로 MCP 도구를 나중으로 미루고 필요할 때 정의를 불러옵니다. 어떤 CLI는 요청마다 모든 스키마를 보냅니다.
• 줄이기 전에 측정하세요. Claude Code의 /context, 또는 어떤 서버에든 도구 목록을 요청하는 40줄짜리 스크립트로.
• 텍스트를 줄이고, 도구는 남기세요. 설명은 무엇을, 언제를 말합니다. 사용 설명서는 에이전트가 필요할 때 읽는 문서로 옮깁니다. 저희 도구는 약 95,000토큰에서 약 38,000토큰으로, 2.5분의 1이 되었습니다.
• 빌드에 상한을 넣으세요. 상한이 없으면 정의는 저절로 다시 불어납니다.

도구 정의의 비용, 그리고 누가 내는가

MCP 클라이언트는 서버에 연결하면 도구 목록을 요청합니다. 각 항목은 이름, 모델을 위해 쓴 설명, 매개변수의 JSON 스키마입니다. 클라이언트는 이 목록을 도구 정의로 바꿔 모델에 보내고, 모델은 이를 통해 도구가 있다는 것과 호출하는 방법을 압니다.

그러니 설명의 단어 하나하나가 모델이 읽는 입력입니다. 얼마나 자주 읽는지는 클라이언트마다 다릅니다.

• Claude Code는 기본적으로 MCP 도구를 나중으로 미룹니다. 2026년 11월 3일 Claude Code 2.1.314를 설치한 상태에서 읽은 문서에 따르면, 세션 시작 시에는 도구 이름과 서버 지침만 불러오고, 정의는 Claude가 그 도구를 필요로 할 때 도구 검색을 통해 불러옵니다. ENABLE_TOOL_SEARCH=false일 때, auto에서 컨텍스트 창의 10%라는 임계값 아래일 때, Claude Opus 4와 Sonnet 4보다 오래된 모델에서, 또는 alwaysLoad가 표시된 서버에서는 정의를 처음부터 불러옵니다.
• 다른 CLI는 다르게 동작합니다. 10월 28일 저희가 직접 한 테스트에서 에이전트에게 "OK"라고만 답하게 했습니다. Claude Code는 저희 도구를 미룬 상태로 67,500토큰에서 시작했고, Codex CLI 0.164는 25,000토큰에서 시작하며 저희 스키마를 한 덩어리로 보내지 않았고, OpenCode는 연결할 때 저희 도구 175개와 브라우저 도구 19개를 불러와 요청마다 보냈습니다. 같은 서버인데 청구서는 크게 달랐습니다.

도구 목록이 바뀌지 않으면 프롬프트 캐시가 비용을 덜어 줍니다. 첫 요청 이후에는 변하지 않는 앞부분을 입력 가격의 일부만 내고 캐시에서 읽습니다. 하지만 공간을 돌려주지는 않습니다. 정의는 여전히 요청마다 컨텍스트 창 안에서 여러분의 코드와 대화 옆에 자리를 차지합니다. 그리고 미루는 방식에도 나름의 비용이 있습니다. 각 도구를 처음 쓰기 전에 검색 단계가 하나 들어갑니다.

2분 만에 내 도구 측정하기

Claude Code에서는 /context를 실행하세요. 창을 출처별로 나누어 보여 주고, 나중으로 미뤄졌거나 필요할 때 불러오는 MCP 도구를 표시합니다. 프로젝트에서 새 세션을 열고 아무것도 입력하기 전에 실행하면, 작업이 시작되기 전에 내 설정이 얼마나 차지하는지 보입니다.

어떤 서버, 어떤 CLI든 서버에 직접 물어보면 됩니다. stdio로 동작하는 MCP 서버는 한 줄에 메시지 하나씩 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입니다. 가장 무거운 도구 10개와 합계가 출력됩니다. 2026년 11월 3일에 저희가 얻은 결과입니다.

4바이트당 1토큰은 추정치입니다. 서버끼리 비교하거나 추세를 보기에는 충분하지만, 청구액을 예측하는 데는 쓸 수 없습니다. 실제 토크나이저는 모델과 텍스트에 따라 달라지며, 저희가 직접 쓴 토큰 38억 개를 세었을 때도 이를 확인했습니다.

위의 파일 서버들은 적당한 크기입니다. 문제는 합계입니다. 이만한 크기의 서버 다섯 개면 저희 같은 서버를 더하기도 전에 이미 20,000토큰입니다.

줄인 것, 그리고 손대지 않은 것

저희가 세운 규칙은 이렇습니다. 도구는 하나도 없애지 않고, 매개변수도 없애지 않으며, 허용 값이나 필수 필드도 없애지 않는다. 에이전트는 모든 기능을 그대로 가져야 했습니다. 바꿀 수 있는 것은 텍스트뿐이었습니다.

1. 도구 설명은 무엇을, 언제를 한 문장에서 세 문장으로 말한다. 어떻게는 말하지 않습니다. 바이트가 쌓여 있던 곳이 바로 그 어떻게였습니다. 규칙, 기본값, 예외 상황, 예시, 그리고 에이전트가 한 번 도구를 잘못 쓴 뒤에 덧붙인 경고들입니다.
2. 매개변수에는 한 문장, 또는 아무것도 쓰지 않는다. 이름, 타입, 허용 값 목록만으로 이미 다 드러나는 경우입니다. 여러 도구에 반복해서 나오는 매개변수(project, author, 티켓 id)에는 어디서나 같은 표준 문장 하나를 붙였습니다.
3. 사용 설명서는 지우지 않고 옮겼다. 도구 계열마다 지침 파일이 있고, 에이전트는 그 계열을 처음 호출하기 전에 그 파일을 읽습니다. 가장 큰 도구, 즉 에이전트 팀을 저장하는 도구는 이제 필드 전체 레퍼런스를 스키마에 싣고 다니는 대신, 에이전트가 요청할 때 도구 호출의 결과로 돌려줍니다.
4. 두 번째 검토에서 모든 사실을 확인했다. 설명에서 뺀 문장은 하나하나 지침 파일에서 찾아보고, 없으면 그곳에 다시 넣었습니다.

결과 일부를 도구별 JSON 바이트로 보여 드립니다.

모두 합쳐 380 KB가 152 KB가 되었습니다. 4 KB를 넘던 도구는 13개였고, 지금도 넘는 것은 4개인데, 담고 있는 필드 수 때문입니다. 이 작업 전체의 생각은 이렇습니다. 도구를 고르려면 모델은 그 도구가 있다는 것과 언제 호출할지만 알면 됩니다. 세부 사항은 실제로 쓰는 순간까지 기다려도 됩니다.

MCP 서버를 만든다면 Claude Code가 이유를 하나 더 줍니다. 처음부터 불러오는 도구 설명은 4,096자에서 잘리고, 검색어를 설명과 맞춰 볼 때도 그 한도 안의 부분만 읽습니다. 그 뒤에 있는 중요한 내용은 한 번도 읽히지 않을 수 있습니다.

시작 파일에도 같은 요령을

고정 비용은 도구 스키마만이 아닙니다. 저희 에이전트는 도구를 쓰기 전에 도구에 관한 지침 파일도 읽는데, 이 파일이 57.7 KB, 약 14,000토큰까지 커져서 시작할 때마다, 재개할 때마다 통째로 읽히고 있었습니다. 한 사용자는 재개한 Codex 에이전트가 몇 분 만에 작업 컨텍스트 한도에 닿았다고 알려 왔습니다.

해결책도 같은 생각이었습니다. 파일은 약 11 KB짜리 색인이 되었습니다. 모든 도구에 적용되는 규칙, 그리고 도구 계열마다 자기 파일을 가리키는 한 줄입니다. 31개의 계열 파일은 그 계열을 처음 호출하기 전에만 읽힙니다. 그 내용은 한 글자도 바꾸지 않았습니다. 백로그만 다루는 에이전트는 데이터베이스 부분을 한 번도 읽지 않습니다.

이 방법은 긴 CLAUDE.md나 AGENTS.md에도 통합니다. 항상 불러오는 파일에는 모든 작업에 필요한 것만 남기고, 나머지는 링크로 연결하세요. 이에 대해서는 AGENTS.md와 컨텍스트 파일 가이드에 더 자세히 썼습니다.

푸시를 실패시키는 예산

저희가 가장 걱정한 숫자는 95,000이 아니었습니다. 일주일 전의 78,000이었습니다. 도구가 늘 때마다 문단이 하나씩 붙었고, 문단 하나하나는 그럴 만했지만, 합계는 7일 만에 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를 넘으면 오류로 종료합니다. 이미 너무 컸던 도구 네 개는 크기와 함께 목록에 올라 있습니다. 한 방향으로만 도는 래칫입니다. 줄어들 수는 있어도 커질 수는 없고, 하나가 줄어들면 스크립트가 숫자를 낮추라고 요구합니다. 이 검사는 푸시할 때마다, 그리고 릴리스 빌드에서도 실행됩니다. 상한을 올릴 수는 있지만, 그것은 파일에 기록되는 결정이지 검사를 통과시키는 수단이 아닙니다.

엿새 뒤인 11월 3일, 같은 검사는 도구 203개, 159,957바이트를 읽었습니다. 도구가 12개 늘었고, 상한까지 43바이트 남았습니다. 다음 도구는 스스로 자리를 만들어야 합니다. 이 검사가 존재하는 이유가 바로 그것입니다.

쓰지 않는 것은 끄세요

가장 싼 토큰은 에이전트가 한 번도 보지 않는 도구의 토큰입니다.

• 서버는 필요한 프로젝트에만 두세요. 사용자 수준에서 선언한 서버는 모든 저장소에 따라옵니다. Claude Code에서는 프로젝트의 .mcp.json에 두면 쓸모 있는 곳에만 머뭅니다.
• alwaysLoad는 소수의 도구에만 쓰세요. Claude Code 문서도 분명히 말합니다. 처음부터 불러오는 도구는 하나하나가 원래 대화에 쓸 수 있었던 컨텍스트를 차지합니다.
• 정의만이 아니라 도구 결과가 더하는 것도 살피세요. 페이지나 표를 통째로 돌려주는 도구는 한 번 호출에 그 정의가 하루 내내 드는 비용보다 더 많이 쓸 수 있습니다.

AgentsRoom에서는 설정 > AgentsRoom 도구에 저희 도구 계열이 무게와 함께 나열되고, 계열 단위로든 도구 하나 단위로든, 모든 프로젝트, 한 프로젝트, 폴더, 에이전트 하나에 대해 끌 수 있습니다. 끈 도구는 에이전트에게 아예 나열되지 않으므로 컨텍스트를 전혀 쓰지 않습니다. AgentsRoom MCP 페이지에서 도구를 소개하고, 세션 추적은 MCP 도구를 포함해 에이전트의 컨텍스트를 무엇이 채웠는지 크기순으로 보여 줍니다.

바꾸지 않은 것

같은 측정에서 다른 비용 두 가지가 드러났지만, 일부러 그대로 두었습니다.

• 시작 브리프: 각 에이전트에게 역할과 상태 보고 방법을 알려 주는 것으로, Claude 기준 중앙값이 약 5,000토큰, 200,000토큰 창의 약 2.5%이며, 두 번째 요청부터는 캐시에서 읽힙니다.
• 각 에이전트가 턴이 끝날 때 쓰는 상태 파일: 로컬 Claude 트랜스크립트 71개로 측정하면 컨텍스트 토큰의 약 2.5%입니다.

둘 중 어느 것을 줄여도 아낄 수 있는 것은 창의 3% 미만이었고, 에이전트 작업의 품질을 해칠 위험이 있었습니다. 도구 정의는 95,000토큰이었습니다. 시간을 쓴 곳은 거기였습니다.

실제로 자주 받는 질문

MCP 도구는 토큰을 얼마나 사용하나요?

도구마다 정의 전체만큼 비용이 듭니다. 이름, 설명, 입력 스키마가 JSON으로 전송됩니다. 대략 4바이트당 1토큰으로 계산하면 됩니다. 2026년 11월 3일 측정 기준으로, 공식 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 서버를 띄워 모든 도구를 측정하고 둘 중 하나라도 넘으면 오류로 종료하는 스크립트를 두고, 푸시할 때마다 실행합니다. 이미 너무 컸던 도구는 줄어들 수는 있어도 커질 수는 없습니다.

요약

MCP 도구는 모델이 읽는 텍스트인데, 그 텍스트를 코드처럼 리뷰하는 사람은 없습니다. 한 번 측정해 보세요. Claude Code에서는 /context, 어떤 서버든 위의 스크립트로 잴 수 있습니다. 그런 다음 각 설명이 무엇을, 언제만 말하게 하고, 어떻게는 에이전트가 필요할 때 읽는 파일로 옮기고, 빌드에 숫자를 넣어 다시 불어나지 못하게 하세요.

저희는 도구를 하나도 없애지 않고 약 95,000토큰에서 약 38,000토큰으로 줄였습니다. 같은 도구로 여러 에이전트를 실행한다면 AgentsRoom은 무료로 내려받을 수 있고, MCP 서버 페이지에서 서버를 한 번만 선언해 모든 CLI와 프로젝트에서 쓰는 방법을 볼 수 있습니다.