Claude Code의 MCP 대용량 출력 한계 측정

Claude Code 문서의 MCP 페이지에는 큰 도구 출력에 대한 짧은 섹션이 있습니다. 여기에는 Claude Code가 "어떤 MCP 도구 출력이든 10,000토큰을 초과하면 경고를 표시한다"고 되어 있고, 기본 최대치는 25,000토큰이며 MAX_MCP_OUTPUT_TOKENS 환경 변수로 변경할 수 있다고 설명합니다. 또한 결과가 한도를 넘으면 Claude Code가 세션의 tool-results 디렉터리 아래 파일로 저장하고, "대화에서는 해당 파일 경로를 이름으로 하는 메시지로 대체한다"고 적혀 있습니다. 두 번째 문단에서는 서버가 tools/list 항목에서 _meta["anthropic/maxResultSizeChars"]를 설정해 하나의 도구에 대해 "기본 디스크 영속화 임계값"을 높일 수 있으며, 그 상한은 500,000자라고 말합니다.

한 문단에서는 한도를 토큰이라고 하고 다음 문단에서는 문자라고 부르며, 문자 임계값에 대한 숫자는 없습니다. 그래서 우리는 어떤 검사가 어디서 작동하는지, 각 경우 Claude가 무엇을 받는지, 그리고 입력 토큰 비용이 얼마인지 확인하고 싶었습니다. 그래서 가능한 한 가장 작은 서버를 만들고 출력 크기를 위아래로 조절해 보았습니다.

설정

모든 작업은 2026-09-16에 수행했으며, 계정의 기본 모델인 claude-opus-5[1m]를 사용하는 Claude Code 2.1.273으로, mktemp -d로 만든 임시 디렉터리 안에서 진행했습니다. 서버는 의존성이 없는 Python 스크립트입니다. stdio를 통해 줄 구분 JSON-RPC를 사용하며 initialize, tools/list, tools/call에 응답하고, 두 개의 도구를 가지고 있습니다. emit_text는 정수 하나 chars를 받아 정확히 그 수만큼의 문자를 반환합니다. emit_text_annotated는 같은 일을 하지만 _meta에 "anthropic/maxResultSizeChars": 300000를 선언합니다.

텍스트는 양끝에 마커가 있는 채움용 문자열입니다. BEGIN-MARKER 줄, 52단어 목록에서 무작위로 뽑은 여덟 단어로 이루어진 번호가 매겨진 줄들, 그리고 END-MARKER: end- 줄로 구성됩니다. Claude가 끝 마커를 인용할 수 있다면 전체 결과가 거기까지 도달한 것입니다. 서버 설정의 환경 변수는 본문을 무작위 CJK 표의문자로 바꾸며, 줄당 59개씩 생성합니다. 우리는 이 설정을 한 실험에 사용했습니다.

서버는 --strict-mcp-config --mcp-config mcp.json로 불러왔기 때문에, 머신에 있는 다른 MCP 서버는 연결되지 않았습니다. 서버 항목은 설정에서 alwaysLoad: true를 지정하는데, 문서에 따르면 이는 도구 검색을 기다리지 않고 세션 시작 시 그 서버의 모든 도구를 로드합니다. 또한 --tools ""를 전달해 내장 도구를 제거했습니다. 그래서 결과가 파일로 옮겨졌을 때, 하나라도 허용하지 않으면 Claude가 그것을 열 방법이 없었습니다. 이렇게 하면 첫 번째 요청이 약 3,300토큰으로 작게 유지됩니다.

프롬프트는 Claude에게 도구를 chars 값 하나로 한 번 호출한 뒤 끝 마커를 답하거나, NOMARKER와 함께 받은 내용을 설명하도록 지시했습니다. 각 실행은 세 턴까지 허용했습니다.

숫자는 claude -p가 ~/.claude/projects/ 아래에 쓰는 대화 기록을 읽었고, JSON 출력의 합계 usage 블록은 사용하지 않았습니다. 대화 기록의 각 assistant 레코드에는 자체 usage가 있습니다. input_tokens, cache_read_input_tokens, cache_creation_input_tokens를 더해 해당 요청의 총 입력을 구합니다. 요청 1은 프롬프트입니다. 요청 2는 프롬프트와 도구 호출, 그리고 Claude Code가 결과 대신 넣은 내용을 포함합니다. 둘의 차이가 모델이 본 결과의 비용입니다. 숫자에 대해 두 가지 작은 주의점이 있습니다. 요청 1의 합계는 첫 세 번의 실행에서는 3,462토큰이었고, 그 이후의 모든 실행에서는 우리가 아무것도 바꾸지 않았는데도 3,295토큰이었기 때문에, 우리는 한 실행 안에서 두 요청만 비교합니다. 또한 JSON 출력에는 매번 작은 Haiku 호출이 하나씩 포함되며, 입력 토큰은 954~965 사이입니다. 이것은 대화의 일부가 아니므로 여기서는 제외했습니다.

Claude Code가 도구 호출과 요청 2 사이에서 무엇을 했는지 보려면, 각 실행은 --debug-file로 디버그 로그도 남겼습니다. 아래의 모든 구성은 두 번씩 실행했습니다. 각 쌍에서 요청 1에서 요청 2로의 증가는 8토큰 이내로 일치했습니다. Read를 사용한 다중 턴 실행은 마지막 요청에서 최대 52토큰 차이가 났습니다.

크기 계단

우리의 단어 목록 텍스트에 대해서는 인라인 행이 토큰당 약 2.6자 정도가 되므로, 45,000자는 17,514토큰이 듭니다. 그때까지는 아무 특이한 일도 일어나지 않았습니다. 어디에서도 경고는 보이지 않았습니다. 30,000자와 45,000자 결과는 문서화된 10,000토큰 경고선보다 높지만, JSON 출력, stderr, 대화 기록, 디버그 로그 어디에도 그에 대한 언급은 없었습니다. 문서에는 그 경고가 Claude Code가 표시하는 것이라고 설명되어 있는데, 헤드리스 실행에는 이를 표시할 화면이 없습니다. 우리는 대화형 UI는 확인하지 않았습니다.

45,000자와 52,000자 사이에서 결과가 더 이상 도착하지 않게 되었습니다. 그 이후로는 요청 2가 요청 1보다 약 1,000토큰 정도만 더 컸지, 2만 토큰 더 큰 것은 아니었고, Claude가 본 것은 두 가지 서로 다른 형태로 들어왔습니다.

두 번의 검사, 두 개의 메시지, 두 가지 파일 형식

52,000자와 62,000자에서는 결과가 다음과 같이 시작하는 블록으로 대체되었습니다:

12345678<persisted-output>
Output too large (51.7KB). Full output saved to: ~/.claude/projects/<dir>/<session>/tool-results/toolu_01Xf....json

Preview (first 2KB):
[
  {
    "type": "text",
    "text": "BEGIN-MARKER: start-99b7...\n000001 kilo victor merge ...

여기에 적힌 파일은 MCP 콘텐츠 배열을 JSON으로 그대로 쓴 것입니다. 다섯 줄짜리이며, 전체 텍스트가 한 줄의 "text" 문자열 안에 들어 있습니다. 52,000자의 경우 그 줄의 길이는 52,891자입니다. 미리보기는 그 JSON의 처음 2KB이므로, Claude는 텍스트의 시작 부분만 보고 끝부분 근처는 전혀 보지 못합니다. 두 실행 모두 NOMARKER로 답했고, 미리보기만 있다고 말했습니다.

66,000자와 70,000자에서는 Claude가 대신 다음을 받았고, 미리보기는 없었습니다:

전체 메시지는 1,423자입니다. 경로 뒤에는 요약과 분석에 대한 지침이 이어집니다. 파일을 "내용의 100%를 읽을 때까지 순차적 청크로 읽으라", 얼마나 읽었는지 말하라, 그리고 몇 차례 실패한 뒤에는 재시도를 멈추라"고 합니다. 여기에 적힌 파일은 .txt이며, 서버가 보낸 텍스트가 그대로 들어 있고 1,116줄로 되어 있으며, 어느 줄도 67자를 넘지 않습니다.

즉, 두 가지 검사가 있고, 각각 다른 흔적을 남깁니다. 문서 페이지만 보고는 그런 식일 것이라고 짐작하지 못했을 것입니다. 하나는 미리보기와 JSON 파일을 동반한 크기 검사입니다. 다른 하나는 오류 메시지와 일반 텍스트 파일을 동반한 토큰 검사입니다. 66,000자에서는 둘 다 적용되지만, Claude가 보는 것은 토큰 메시지입니다.

디버그 로그는 토큰 검사가 어떻게 작동하는지 일부 보여줍니다. 52,000자부터의 모든 실행에서 도구가 반환된 직후 /v1/messages/count_tokens로의 요청이 나타나고, 그 다음에 Persisted tool result to ...가 이어집니다. 45,000자 이하에서는 그런 요청이 없습니다. 따라서 토큰 검사는 결과가 문자 기준으로 충분히 길어졌을 때만 API의 토큰 계산 엔드포인트를 호출합니다. 그보다 짧은 길이에서는 결과가 계산 없이 그대로 컨텍스트에 들어갑니다.

그것은 경계선도 설명해 줍니다. 62,000자에서 우리 텍스트는 위의 비율로 약 24,100토큰으로, 25,000 바로 아래입니다. 개수는 아마도 제한 아래로 돌아왔고, 크기 검사만 적용되었습니다. 66,000자에서는 주석이 달린 도구(아래)를 통해 같은 텍스트를 인라인으로 전달하자 요청이 25,568토큰 늘어났고, 도구 호출도 포함되었습니다. 이는 제한을 약간 넘는 수치였고, 토큰 검사가 적용되었습니다. 전환점은 계산상 그래야 하는 지점에 정확히 떨어집니다.

한 번도 집계되지 않은 결과

표의 마지막 행이 바로 이 글을 쓰게 된 이유입니다. 무작위 CJK 한자는 문자당 약 2토큰이 들었고, 우리의 영어 더미는 약 0.39토큰이었습니다. 우리는 그 한자 24,000개를 반환했습니다. 이는 30,000자 실행보다 문자 수가 적고, UTF-8 기준 71,084바이트로 파일로 옮겨졌던 52,000자 결과보다 바이트 수는 더 큽니다.

Claude Code는 count_tokens 요청을 보내지 않았고 결과를 옮기지도 않았습니다. 전체 텍스트가 컨텍스트에 들어갔고, 요청 2는 49,964토큰 늘어났으며, Claude는 두 실행 모두에서 끝 표시자를 인용했습니다. CLI의 total_cost_usd 기준으로 각 실행은 0.51달러가 들었고, 파일로 옮겨진 실행들은 약 0.02달러였습니다.

문서화된 25,000토큰 최대치는 한 번도 검사되지 않았습니다. 가장 그럴듯한 이유는 집계 여부를 문자 수로 판단하는데, 24,000자는 크게 보이지 않았기 때문입니다. 크기 검사도 작동하지 않았으므로, 이것 역시 UTF-8 바이트 기준은 아니라고 볼 수 있습니다. 우리가 보기에는 두 검사 모두 문자 수를 보고 있고, 토큰 제한은 문자 수가 긴 결과에 대해서만 적용됩니다.

우리는 CJK만 테스트했습니다. 문자당 토큰 비율이 낮은 다른 것도 다음에 시험해 볼 만한데, 예를 들면 base64, 짧은 키로 가득 찬 축약 JSON, 또는 긴 16진수 문자열 같은 것들입니다. 우리는 그것들을 측정하지 않았으므로, 같은 방식으로 통과하는지는 알 수 없습니다.

두 개의 조절 손잡이가 바꾸는 것

어느 설정이 어떤 검사를 움직이는지 보기 위해 네 가지 구성을 더 실행했습니다.

MAX_MCP_OUTPUT_TOKENS=50000과 66,000자 결과를 사용했을 때, 토큰 검사는 잠잠했습니다. count_tokens 요청도 없고, 오류 메시지도 없었습니다. 하지만 결과는 여전히 도착하지 않았습니다. Claude는 미리보기(65.6KB)를 받았고, 요청 2는 1,065토큰 늘어났습니다. 환경 변수를 올려도 결과가 컨텍스트로 들어오지는 않았습니다. 크기 임계값을 정하는 것이 무엇이든, 그 변수로는 바뀌지 않았습니다.

MAX_MCP_OUTPUT_TOKENS=5000과 30,000자 결과를 사용했을 때는, 기본 설정에서는 인라인으로 들어가던 결과가 Claude Code에서 count_tokens를 호출하고 "허용된 최대 토큰을 초과했습니다" 메시지로 결과를 대체했습니다. 그 동일한 결과를 우리가 인라인으로 측정했을 때는 11,687토큰이었습니다. 따라서 Claude Code가 언제 집계할지 판단하는 문자 길이는 제한에 따라 달라집니다. 기본값에서는 45,000자와 52,000자 사이에 있습니다. 제한을 5,000으로 두면 30,000자만으로도 집계를 유발했고, 제한을 50,000으로 두면 66,000자는 그러지 못했습니다. 정확한 공식은 알아내지 못했습니다.

주석이 달린 도구는 문서가 설명하는 대로, 그리고 그 이상으로 동작했습니다. 66,000자에서는 전혀 집계 없이 인라인으로 들어왔고, 요청 2는 25,568토큰 늘어났습니다. 이는 25,000 기본값을 넘는 수치로, 문서화된 동작과 일치합니다. 즉 anthropic/maxResultSizeChars를 선언한 도구는 MAX_MCP_OUTPUT_TOKENS 설정과 무관하게 그 문자 제한을 텍스트에 적용합니다. 320,000자에서는, 우리가 선언한 300,000자를 넘겼음에도, Claude는 미리보기(317.8KB)를 받았고 역시 집계는 없었습니다. 우리가 실행한 실험들에서, 주석이 달린 도구의 텍스트가 거치는 검사는 작성자가 정한 문자 제한뿐이었습니다.

Claude가 파일을 어떻게 다루는가

대체 메시지는 Claude가 파일을 열 수 있을 때에만 도움이 되므로, Read 도구를 허용한 상태에서 세 가지 구성을 더 실행했습니다.

이전 실행에서 사용한 타깃 프롬프트(끝 표시자만 포함)와 66,000자 결과를 사용했을 때, Claude는 offset: 1100으로 파일을 한 번 읽어 마지막 17줄을 가져왔고, 올바르게 답했습니다. 마지막 요청은 5,245토큰을 사용했는데, 같은 결과를 주석이 달린 도구를 통해 인라인으로 전달했을 때의 28,867토큰보다 적었습니다. Read 실행에는 Read 도구 정의도 포함되지만(약 600토큰), 그 점을 감안해도 그렇습니다. 출력의 일부에 관한 질문이라면 파일 경로가 비용을 5분의 1도 안 되게 줄여 주었습니다. Claude는 요약용으로 적어 둔 "100%를 읽기" 지시도 무시했지만, 아무 문제도 없었습니다.

그런 다음 우리는 모든 줄이 필요한 질문을 던졌습니다. 즉, "zulu"라는 단어를 포함하는 줄이 몇 개인지였습니다. 66,000자 결과에 대한 토큰 확인 사례에서 Claude는 400줄씩 세 번의 병렬 Read(오프셋 1, 401, 801)를 수행했고, 166이라고 답했는데 이는 맞는 값입니다. 최종 요청에는 두 번의 실행에서 각각 33,185개와 33,133개의 토큰이 실렸습니다. 이는 인라인 요청보다 약 4,300토큰 더 많은 수치이며, Read 도구의 정의를 제외하면 약 3,700토큰 정도입니다. 차이의 대부분은 아마도 Read가 각 줄마다 붙이는 줄 번호 접두사 때문일 것입니다. 또한 요청이 하나 더 들었습니다.

52,000자 결과, 즉 크기 확인 사례에서는 파일이 52,891자짜리 한 줄에 텍스트가 들어 있는 JSON 배열입니다. 우리는 Read가 여기서 어려움을 겪을 것으로 예상했습니다. 그러나 그렇지 않았습니다. 단일 Read가 전체 52,935자를 반환했고, Claude는 125줄을 셌는데 이는 정확한 값입니다. 최종 요청에는 각각 26,269개와 26,254개의 토큰이 실렸습니다. Claude Code는 이 실행들에서 count_tokens를 두 번 호출했는데, 한 번은 MCP 결과에 대해, 한 번은 Read 결과에 대해 호출했습니다. 이는 같은 크기 기반 카운트가 Read 출력에도 적용된다는 생각과 들어맞습니다. 우리는 그 이상은 살펴보지 않았습니다.

따라서 Claude가 파일을 읽을 수 있는 방법이 있다면, 문맥 밖으로 옮겨진 결과는 사라지지 않습니다. 부분적인 질문이라면 더 저렴하고, 전체 읽기라면 조금 더 비용이 듭니다. 세션이 --tools ""를 사용한 우리 실행처럼 Claude에게 파일 도구를 전혀 주지 않으면, 대체물만이 Claude가 얻는 전부입니다. 그런 실행들은 모두 NOMARKER라고 답하고 그 이유를 설명했습니다.

서버 작성자 관점에서 얻은 점

실용적으로 읽어보면, 그리고 이는 문서에 명시된 내용이 아니라 우리의 해석이지만, 토큰이 빽빽한 도구 출력으로부터 문맥을 보호하기 위해 25,000토큰 한도에 의존하지 마십시오. 이 한도는 긴 영어 텍스트에는 실제로 적용됩니다. 하지만 몇 개의 문자에 많은 토큰을 담는 텍스트에서는 검사가 아예 실행되지 않을 수 있습니다. 도구가 CJK, 인코딩된 바이너리 덩어리, 또는 그 밖의 밀도 높은 콘텐츠를 반환할 수 있다면, 문자 수가 아니라 토큰 수나 페이지 수로 서버에서 제한하십시오.

두 번째로 얻은 점은 환경 변수와 주석이 같은 일을 하는 두 가지 방법이 아니라는 것입니다. MAX_MCP_OUTPUT_TOKENS를 올려도 토큰 검사만 이동할 뿐입니다. 우리가 45,000자와 52,000자 사이에서 확인한 크기 검사는 여전히 결과를 파일로 옮깁니다. 주석은 크기 검사를 옮기고, 텍스트에 대한 토큰 검사를 끕니다. 도구가 정말로 66,000자를 인라인으로 반환해야 한다면, 우리 실행에서는 주석이 그 설정이었습니다.

세 번째는 파일 형식에 관한 것입니다. 토큰 검사로 옮겨진 결과는 줄바꿈을 유지한 일반 텍스트로 저장되므로, Read의 오프셋과 제한이 예상대로 동작합니다. 크기 검사로 옮겨진 결과는 텍스트가 한 줄에 들어 있는 JSON 배열로 저장됩니다. Read는 여기서 52,891자짜리 한 줄을 한 번의 호출로 처리했지만, 그 한계가 어디까지인지는 테스트하지 않았습니다.

우리가 측정하지 않은 것

실험마다 텍스트 형태는 하나뿐이었습니다. 영어 같은 채움 텍스트와 무작위 CJK였습니다. 두 문자 임계값이 정확히 어디인지, 즉 토큰 수를 유발하는 길이와 크기 검사를 유발하는 길이는 정확히 알지 못합니다. 기본 설정에서 이 텍스트에 대해 둘 다 45,000자와 52,000자 사이에 있다는 것만 압니다.

모든 것은 헤드리스로 실행했습니다. 10,000토큰 경고는 표시용으로 문서화되어 있으며, 우리는 이를 확인하기 위해 대화형 세션을 열지 않았습니다. 문서에 따르면 항상 MAX_MCP_OUTPUT_TOKENS의 적용을 받는 이미지 콘텐츠는 테스트하지 않았습니다.

우리는 하나의 모델만 사용했으며, 100만 토큰 컨텍스트를 가진 모델이었습니다. 다른 모델이나 컨텍스트 크기에서도 검사 동작이 같은지는 테스트하지 않았습니다. 머신의 사용자 수준 훅과 플러그인은 모든 실행에서 활성화되어 있었습니다. 모든 실행에서 동일했고, 각 비교는 하나의 실행 안에서 이루어졌지만, 그것들은 존재했습니다.

우리는 총 39번의 claude -p 호출을 했습니다. 그중 9번은 셸 루프의 단어 분리 버그로 낭비되었습니다. 실행 라벨과 크기를 하나의 인자로 넘겨 다른 모든 인자가 밀려버렸고, 그 결과 Claude는 존재하지 않는 도구를 호출하라는 요청을 받았습니다. 이들은 위의 어떤 수치에도 포함되지 않습니다.

재현하기

이것은 우리의 서버를 더 짧게 줄인 버전입니다. 12단어 목록, 더 단순한 마커, 그리고 CJK 전환이 없습니다. 문자당 토큰 비율은 위 숫자의 출처가 된 52단어 버전과 정확히 같지는 않을 것이므로, 경계 행이 조금 움직일 것으로 예상하십시오.

123456789101112131415161718192021222324252627282930313233import sys, json, random
WORDS = "alpha bravo charlie delta echo foxtrot golf hotel river stone cloud paper".split()

def make_text(n):
    rng = random.Random(n)
    head, tail = "BEGIN-MARKER\n", f"\nEND-MARKER: end-{n}\n"
    body, i = "", 0
    while len(body) < n - len(head) - len(tail):
        i += 1
        body += f"{i:06d} " + " ".join(rng.choice(WORDS) for _ in range(8)) + "\n"
    return head + body[: n - len(head) - len(tail)] + tail

schema = {"type": "object", "properties": {"chars": {"type": "integer"}}, "required": ["chars"]}
TOOLS = [
    {"name": "emit_text", "description": "Returns filler text.", "inputSchema": schema},
    {"name": "emit_text_annotated", "description": "Same, larger limit.", "inputSchema": schema,
     "_meta": {"anthropic/maxResultSizeChars": 300000}},
]
for line in sys.stdin:
    req = json.loads(line)
    if "id" not in req:
        continue
    m = req["method"]
    if m == "initialize":
        res = {"protocolVersion": req["params"]["protocolVersion"],
               "capabilities": {"tools": {}}, "serverInfo": {"name": "big", "version": "0.1"}}
    elif m == "tools/list":
        res = {"tools": TOOLS}
    elif m == "tools/call":
        res = {"content": [{"type": "text", "text": make_text(int(req["params"]["arguments"]["chars"]))}]}
    else:
        res = {}
    print(json.dumps({"jsonrpc": "2.0", "id": req["id"], "result": res}), flush=True)

123456789LAB=$(mktemp -d) && cd "$LAB"   # save the server above as server.py here
printf '{"mcpServers":{"big":{"type":"stdio","command":"python3","args":["%s/server.py"],"alwaysLoad":true}}}' "$LAB" > mcp.json
for n in 45000 52000 66000; do
  claude -p "Call mcp__big__emit_text once with chars=$n, then reply with the END-MARKER value or NOMARKER." \
    --output-format json --max-turns 3 --strict-mcp-config --mcp-config mcp.json \
    --allowedTools mcp__big__emit_text --tools "" --debug-file "debug-$n.log" | jq -r .session_id
  grep -c count_tokens "debug-$n.log"
done
# then repeat the 66000 run with MAX_MCP_OUTPUT_TOKENS=50000 in front: it still became a file for us

각 세션 ID마다 ~/.claude/projects/ / .jsonl을 열고, 각 어시스턴트 레코드의 usage에 있는 세 입력 필드를 모두 더한 다음, 첫 번째 요청을 두 번째 요청에서 뺍니다. 그런 다음 /tool-results/를 확인해 두 파일 형식 중 어느 쪽을 받았는지 봅니다. 제목의 발견을 확인하려면 단어 목록을 임의의 CJK 문자로 바꾸고 그 문자 24,000개를 요청해 보세요. 우리 머신에서는 그 실행이 한 번 시도할 때마다 약 $0.51이 들었습니다.

Rulestack는 Claude Code와 주변 도구를 위한 rules 파일, skills, hooks를 만들며, rulestack.gumroad.com 에서 확인할 수 있습니다. 이 글의 모든 숫자는 가게를 운영하는 같은 머신에서 나온 것이며, 서버는 여러분의 머신에서도 다시 실행해 볼 수 있을 만큼 작습니다.

base64와 minified JSON 버전을 실행해 보면, 숫자를 @ai-shop.bsky.social 에 올리겠습니다.

출처

• 원문: https://dev.to/rulestack/claude-codes-25000-token-mcp-limit-let-a-49964-token-result-through-we-measured-both-checks-54nc (2026-09-23 · Rulestack)