클로드 코드(Claude Code) MCP 토큰, 도구 검색 켰을 때와 껐을 때 비교

클로드 코드에 MCP 서버 3개를 붙였을 때, 기본 설정에서는 입력 토큰이 381개만 늘었습니다. 그런데 도구 검색을 끄고 같은 서버 3개를 붙이니 7,020개가 늘었습니다. 켰을 때의 18.4배예요. Claude Code MCP 토큰이 어디서 불어나는지 궁금했다면 이 차이부터 숫자로 확인해 보세요.

MCP 토큰을 가르는 MCP 도구 검색 설정

컨텍스트 창 문서에 따르면 기본값에서는 MCP 도구 이름만 목록으로 넣고, 전체 스키마는 미뤄 두었다가 작업에 필요할 때 도구 검색(tool search)으로 불러옵니다. ENABLE_TOOL_SEARCH=auto로 두면 스키마가 컨텍스트 창의 10% 안에 들 때 미리 불러오고, ENABLE_TOOL_SEARCH=false로 두면 전부 불러옵니다. 이번 측정에서 MCP 도구 24개가 들어 있던 서버 3개는 기본값에서 입력 토큰을 381개, 도구 검색을 끈 상태에서는 7,020개 늘렸습니다(도구 검색을 끈 빈 프로젝트 대비). MCP 서버를 여럿 붙인다면 ENABLE_TOOL_SEARCH를 따로 바꿔 두지 않았는지부터 확인하는 편이 좋습니다.

함께 읽을 글

• 클로드 코드(Claude Code) 토큰 절약, 직접 재 보니 먼저 바꿀 3가지
• MCP 서버 직접 만들기, 클로드 코드에 붙여 토큰과 호출 확인
• 클로드 코드(Claude Code) 토큰, CLAUDE.md와 MCP 서버 직접 재 보니

도구 검색을 끄면 토큰이 몇 배로 늘까요?

결론부터 말하면, 측정에 쓴 서버 3개 기준으로 MCP 서버가 늘린 입력 토큰은 도구 검색을 켰을 때 381개, 껐을 때 7,020개였습니다. 껐을 때의 값은 도구 검색을 끈 빈 프로젝트와 비교해서 구했습니다. 조건마다 3번씩 재서 중앙값을 썼습니다.

표를 보면 눈에 띄는 점이 하나 더 있습니다. MCP 서버를 하나도 붙이지 않은 빈 프로젝트도 도구 검색을 끄기만 했는데 입력 토큰이 +22,493개 늘었죠. 참고로 서버 3개를 붙인 세션의 도구 목록에는 MCP 도구 24개가 들어 있었습니다.

도식출처: Claude Code 입력 토큰 측정

숫자가 이렇게 벌어진다면 도구 검색은 정확히 무슨 일을 하는 걸까요? 공식 문서의 설명을 이어서 보겠습니다.

MCP 도구 검색은 무엇을 해 주나요?

컨텍스트 창 문서를 보면, 세션이 시작될 때 MCP 도구는 이름만 목록으로 들어갑니다. Claude가 어떤 도구를 쓸 수 있는지만 알게 하는 거죠. 도구의 전체 스키마는 기본값으로 뒤로 미뤄 두었다가, 작업에 필요해지면 도구 검색으로 그 도구의 스키마만 불러옵니다.

문서에서 이 항목은 터미널에 보이지 않는 내용으로 분류됩니다. 그래서 MCP 서버를 여러 개 붙여도 화면만 봐서는 컨텍스트가 얼마나 찼는지 알기 어렵습니다. 혼자 에이전트에게 일을 맡기는 동안에도 이 부분은 조용히 입력 토큰에 더해지는 셈이에요.

도구 검색은 언제 꺼지고, 끄면 무엇이 달라지나요?

문서가 밝힌 방법은 환경 변수입니다. 아무것도 설정하지 않으면 위에서 말한 기본 동작을 따르고, 값을 바꾸면 스키마를 불러오는 방식이 달라집니다.

ENABLE_TOOL_SEARCH=auto
ENABLE_TOOL_SEARCH=false

• auto: 스키마가 컨텍스트 창의 10% 안에 들어갈 때 미리 불러옵니다.
• false: 모든 스키마를 처음부터 불러옵니다. 이번 측정에서 도구 검색을 끈 조건이 이 값입니다.

그럼 서브에이전트는 어떨까요? 문서에 따르면 서브에이전트도 같은 MCP와 스킬 구성을 불러오고, 이 몫은 서브에이전트 자신의 컨텍스트에 쌓입니다. 서브에이전트를 자주 띄우고 있다면 MCP 구성의 크기도 함께 따져 보는 편이 좋겠습니다.

도식출처: 근거를 바탕으로 코드가 그린 도식

빈 프로젝트까지 늘어난 이유는 알 수 있나요?

이 측정만으로는 원인을 가를 수 없습니다. 문서는 도구 검색을 끄면 MCP 도구 스키마를 모두 불러온다고만 설명합니다. MCP 서버가 없는 상태에서 22,493개가 늘어난 이유는 따로 밝히지 않습니다.

이럴 때는 직접 같은 조건으로 재 보는 것이 가장 확실합니다. 새 임시 폴더에서 아래 명령을 한 턴 실행하고, 결과 JSON의 새 입력, 캐시 쓰기, 캐시 읽기 토큰을 더해서 설정끼리 비교해 보세요.

claude -p "Reply with only: OK"

측정 조건과 한계

이 값이 내 환경에도 그대로 맞을까요? 아래 조건을 보고 판단해 보세요.

• 환경: Claude Code 2.1.303, 모델 claude-opus-5-5, darwin arm64, Node.js v22.23.1
• 방식: 조건마다 새 임시 프로젝트 폴더에서 한 턴만 실행했고, 3번씩 번갈아 잰 중앙값을 썼습니다. 뺀 회차는 없습니다.
• 격리: --setting-sources project로 사용자 설정, 플러그인, 훅을 불러오지 않았고, --strict-mcp-config로 조건에 적은 서버만 붙였습니다.
• 서버: @modelcontextprotocol/server-filesystem 1.0.0, @modelcontextprotocol/server-memory 1.0.0, @modelcontextprotocol/server-sequential-thinking 1.0.0 (npm으로 설치해 node로 실행)

한계도 분명합니다. 요청 한 번의 입력 토큰만 쟀기 때문에 대화가 길어질 때나 실제로 도구를 호출할 때의 토큰은 이 표에 없습니다. 서버의 종류와 도구 수가 달라지면 결과도 달라질 수 있으니, 18.4배를 모든 MCP 구성에 그대로 적용하지는 마세요.

MCP 서버를 붙일 때 확인할 것

서버를 새로 붙였다면 아래 항목을 차례로 점검해 보세요. 모두 비용 관리 문서와 이번 측정에 근거한 항목입니다.

• 셸이나 실행 스크립트에 ENABLE_TOOL_SEARCH=false가 남아 있지 않은지 확인합니다. 이번 측정에서는 이 값 하나로 입력 토큰이 크게 달라졌습니다.
• 서버를 붙이기 전과 후에 위의 한 턴 명령을 실행해 입력 토큰을 비교합니다.
• Pro, Max, Team, Enterprise 플랜이라면 /usage의 사용량 분석에서 MCP 서버별 비중을 봅니다. 서버 비중은 그 서버의 도구 결과를 쓴 요청만 셉니다. v2.1.222 이전에는 비중이 실제보다 크게 잡혔습니다.
• /usage의 프롬프트 캐시 줄(v2.1.251 이상)에서 캐시 미스를 확인합니다. v2.1.260 이상에서는 likely cause: tool definitions changed처럼 추정 원인도 나옵니다. 도구 정의를 바꾼 뒤 미스가 늘었다면 이 줄부터 보세요.