Claude Code MCP 컨텍스트 과부하: 원인 찾기와 큰 출력 줄이기
MCP 서버 수를 줄이기 전에 컨텍스트가 언제 늘어나는지 확인하세요. 도구 검색은 정의 로딩을 늦추고, 필터링과 분할 조회는 큰 반환값을 줄입니다. 정리한 뒤에도 같은 기록에 접근하고 필요한 작업을 끝낼 수 있어야 합니다.
목차

Claude Code에서 MCP를 연결한 뒤 컨텍스트가 빨리 찬다면 도구를 호출하기 전, 큰 결과를 받은 직후, 대화가 길어진 뒤를 나누어 확인하세요. 도구 정의가 부담이면 Tool Search의 적용 상태를 살펴보고, 결과가 부담이면 조회 범위와 반환 형식을 줄입니다. 오래 쌓인 기록이 부담이면 현재 작업 상태를 남긴 뒤 대화를 압축하거나 새로 시작합니다.
서버를 몇 개 이하로 유지해야 한다는 정답은 없습니다. 오류 로그를 통째로 보내는 서버 하나가 문제일 수도 있고, 필요한 서버를 꺼서 조사는 빨라 보이는데 근거를 찾지 못하게 될 수도 있습니다. 목표는 사용량 숫자만 낮추는 것이 아니라, 같은 자료에 접근하면서 같은 작업을 완료하는 것입니다.
예를 들어 배치 작업의 실패 원인을 찾는다면 성공 조건은 “대화가 짧아졌다”가 아닙니다. 실패한 작업을 특정하고, 원본 오류를 확인하고, 수정 후 확인할 항목을 남기는 데까지 이어져야 합니다. 아래에서는 이 상황을 예로 들어 정리 방법을 설명합니다. 예제 데이터는 설명용이며 실제 Claude Code 실행이나 성능 측정 결과가 아닙니다.
컨텍스트가 늘어난 시점부터 찾으세요
/context를 열어 사용량을 확인하고, 세부 항목이 접혀 있으면 /context all로 펼칩니다. 표시되는 용량과 항목을 자신의 세션에서 확인하세요. 공식 컨텍스트 설명에 나온 그림의 수치를 그대로 자신의 예산으로 삼으면 안 됩니다. 컨텍스트에는 대화 외에도 지침, 읽은 파일, 도구 결과와 시작 시 로드되는 자료가 들어갑니다.
다음 표는 원인을 확정하는 검사가 아니라 다음 확인 대상을 좁히는 방법입니다. 느리다는 느낌만으로 컨텍스트 부족이라고 단정하지 마세요.
| 확인할 시점 | 살펴볼 항목 | 다음에 할 일 |
|---|---|---|
| 새 대화에서 외부 조회를 하기 전 | MCP 관련 정의와 시작 자료의 비중 | 필요한 도구가 무엇인지 적고 Tool Search 적용 조건을 확인합니다. |
| 특정 조회 한 번을 마친 직후 | 그 호출의 결과 크기와 /context 변화 | 같은 질문을 더 좁은 시간·대상 범위로 조회할 수 있는지 봅니다. |
| 재시도와 파일 읽기를 여러 번 한 뒤 | 이미 끝난 조사, 반복된 출력, 바뀐 결정 | 현재 유효한 판단과 원본 위치를 남기고 대화를 정리합니다. |
| 필요한 도구가 보이지 않거나 호출이 실패할 때 | /mcp의 연결·인증·차단 상태 | 연결 문제를 먼저 구분합니다. 사용량 감소를 해결의 증거로 삼지 않습니다. |

배치 실패 조사라면 먼저 작업 ID와 조사 기간을 고정합니다. 전체 로그 조회 대신 “이 작업 ID의 실패 이벤트와 바로 앞뒤 기록”을 요청하고, 호출 전후의 사용량을 비교합니다. 질문과 기간까지 바꾸면 출력 감소가 정리 덕분인지, 다른 자료를 조회했기 때문인지 구분하기 어렵습니다.
메모리 사용량이나 CPU가 높아지는 현상은 별도로 볼 필요가 있습니다. 현재 /doctor는 수정안을 제안하고 확인을 받는 skill입니다. 무조건 읽기 전용 진단이라고 생각하지 말고 제안 내용을 확인하세요. 읽기 전용 설치 진단인 claude doctor와도 다릅니다. 명령어 안내와 문제 해결 안내를 참고할 수 있습니다. 안전 모드는 MCP뿐 아니라 여러 사용자 설정을 함께 제외하므로, 그 결과만으로 특정 MCP가 원인이라고 결론 내리면 안 됩니다.
Tool Search가 적용되는 경로인지 확인하세요
현재 기본 설정에서는 MCP 정의를 필요할 때 검색하지만 도구 이름·서버 지침은 시작부터 남습니다. auto의 10% 기준은 별도 설정입니다. Tool Search 설정 안내
ENABLE_TOOL_SEARCH | 동작 |
|---|---|
| 미설정 | 지원 경로의 현재 기본 동작 |
true | 지원되면 정의 로딩을 미룹니다. |
false | 정의를 처음부터 로드합니다. |
auto / auto:N | 컨텍스트의 10% / 지정 비율 기준, N은 0–100 |
공급자 경로도 확인해야 합니다.
| 조건 | 확인할 점 |
|---|---|
다른 공급자의 ANTHROPIC_BASE_URL | 기본 비활성화. true라도 프록시가 tool_reference를 지원해야 합니다. |
| Google Agent Platform | v2.1.221 이후 4.5 이상 모델은 기본 활성화. 이전 세대는 강제로 켤 수 없습니다. |
| Foundry | Azure 배포 서버가 tool_reference를 거부하면 강제 활성화가 불가능합니다. |
| 베타 기능 비활성화·관리 정책 | 검색을 끄거나 제한할 수 있습니다. |
서버 alwaysLoad와 도구별 anthropic/alwaysLoad는 지연에서 제외됩니다. 공식 MCP 문서에서 공급자별 적용 조건을 확인하세요.
검색이 적용되더라도 호출 결과와 이전 대화가 작아지는 것은 아닙니다. 배치 조사에서 도구를 찾는 데는 문제가 없는데 로그를 받은 뒤 사용량이 크게 늘었다면, 설정 값을 반복해서 바꾸기보다 반환값을 먼저 살펴보세요. 필요한 도구의 정의가 뒤늦게 보이는 것 자체도 서버가 끊겼다는 증거는 아닙니다.
큰 출력은 무조건 잘리는 것이 아닙니다
MCP는 10,000토큰부터 경고하며 기본 상한은 25,000토큰입니다. 이미지 없는 성공한 전경 텍스트는 토큰 상한 또는 기본 50,000자 초과 시 파일 참조로 반환합니다. 오류 텍스트는 약 11,000자부터 앞뒤 5,000자를 남기며, 이미지는 토큰 제한을 받습니다. 출력 제한 안내
도구 선언의 _meta["anthropic/maxResultSizeChars"]는 문자 기준을 바꿉니다. 최대 500,000자이며 MAX_MCP_OUTPUT_TOKENS와는 별개입니다. Anthropic 전용 설정입니다. 도구별 한도 설정
따라서 “25K를 넘었으니 필요한 기록이 없어졌다”라고 단정하지 말고 반환된 내용을 확인하세요. 파일 참조가 있다면 실패 원인을 판단하는 데 필요한 부분을 좁혀 읽습니다. 파일 전체를 다시 대화에 넣으면 저장으로 분리한 큰 출력이 다시 컨텍스트를 채울 수 있습니다. 오류 응답이라면 생략 표시를 확인하고, 필요한 중간 구간을 더 좁은 요청으로 받아야 합니다.
여기서 토큰, 문자, UTF-8 바이트는 다른 단위입니다. 한국어 문자열의 글자 수를 세거나 파일 크기를 비교해도 실제 모델 토큰 수를 얻은 것은 아닙니다. 출력 상한 역시 대화 전체의 컨텍스트 용량과 같지 않습니다.
한도를 올리는 방법은 필요한 기록을 받을 수 있게 해 주지만, 그 자체로 출력이 작아지지는 않습니다. 먼저 어떤 근거가 필요한지 정한 뒤 요청을 좁히세요. 조회 도구가 필터나 분할 조회를 지원하지 않는다면 프롬프트에 “짧게”라고 쓴 것만으로 서버가 작은 결과를 보내 준다고 기대할 수는 없습니다.
서버는 되돌릴 수 있게 정리하세요
/mcp로 서버 설정을 보존하면서 프로젝트별로 끌 수 있습니다. 연결된 도구는 다음 요청부터 사용 가능해질 수도 있습니다. 서버 비활성화와 도구 가용성
조사 중에는 “지금 필요한 접근”을 기준으로 선택합니다. 배치 로그와 작업 상태를 읽는 서버는 유지하고, 이번 조사와 무관한 디자인 자료나 다른 프로젝트의 도구는 잠시 끌 수 있습니다. 최종 확인에 필요한 서버는 다시 켤 시점을 기록합니다. 설정 삭제를 첫 단계로 삼으면 되돌리는 비용이 커집니다.
| 서버의 역할 | 이번 작업에서의 처리 |
|---|---|
| 실패 로그와 작업 상태 조회 | 유지합니다. 대신 조회 기간과 작업 ID를 좁힙니다. |
| 다른 서버와 같은 자료를 조회 | 어느 쪽이 필요한 기록과 권한을 갖췄는지 확인한 뒤 한쪽을 잠시 끕니다. |
| 현재 조사에는 불필요하지만 나중에 검증에 필요 | 잠시 끄고 다시 켤 조건을 남깁니다. |
| 필요한 자료를 늘 통째로 반환 | 접근은 유지하고 출력 형식을 개선합니다. |
도구가 사라졌다면 설정 유무, 비활성화 여부, 연결 중인지, 인증이 필요한지, 정책으로 차단됐는지를 구분하세요. 컨텍스트를 줄였는데도 인증 오류가 그대로라면 정리로 해결할 문제가 아닙니다. 연결을 위해 권한을 넓히거나 보안 설정을 완화하는 일을 컨텍스트 정리와 묶지 마세요.
API 응답의 529 overloaded_error도 별개입니다. Claude API에서는 서비스의 일시적인 과부하를 뜻합니다. 상태 코드, 오류 유형과 요청 ID를 확인해야 하며, MCP를 끄거나 대화를 압축하면 복구된다는 근거는 없습니다. Claude API 오류 안내
직접 만든 MCP라면 필요한 근거를 작은 결과에 담으세요
배치 조사에 전체 로그가 필요하지 않은 경우, 서버가 먼저 기간과 작업 ID로 필터링하고 오류별 건수와 대표 기록을 반환하게 설계할 수 있습니다. 핵심은 요약의 크기보다 요약에서 원본으로 이어지는 경로입니다. 건수만 반환하면 원인을 확인할 수 없고, 대표 오류 한 줄만 반환하면 다른 실패 유형을 놓칠 수 있습니다.
다음은 우리가 설계할 수 있는 반환 예시입니다. 필드 이름과 값은 설명용이며 MCP가 강제하는 표준 필드가 아닙니다.
{
"jobId": "batch-204",
"window": {
"from": "2026-10-06T09:00:00Z",
"to": "2026-10-06T09:10:00Z"
},
"matchedErrors": 37,
"groups": [
{
"kind": "upstream_timeout",
"count": 31,
"sampleRecordId": "log-801"
},
{
"kind": "invalid_payload",
"count": 6,
"sampleRecordId": "log-926"
}
],
"recordsShown": 2,
"nextCursor": "page-2"
}이 반환을 받은 뒤에는 두 오류를 각각 확인합니다. log-801의 앞뒤 기록을 읽고, log-926에서 잘못된 입력 항목을 확인합니다. 대표 기록만으로 원인이 같다고 단정할 수 없다면 다음 페이지나 다른 표본을 요청합니다. 예제의 31건과 6건을 더하면 37건이지만, 이 계산은 데이터의 진위를 입증하지 않습니다. 서버가 집계한 범위와 누락 여부를 별도로 확인할 수 있어야 합니다.

구현할 때는 다음 관계를 명확하게 만드세요.
- 요청 범위: 작업 ID, 기간, 필터와 페이지 크기에 기본값을 두고, 반환 결과에도 실제 적용 범위를 표시합니다.
- 요약과 상세: 요약에서 쓰는 기록 ID가 상세 조회에서도 통하도록 합니다. 요약을 만들 때 오류 종류나 필수 필드를 버리지 않습니다.
- 분할 조회: 정렬 순서를 고정하고, 다음 페이지에서 중복되거나 빠진 기록을 구분할 수 있도록 합니다. 계속 바뀌는 로그라면 조회 기준 시점을 유지하는 방법도 필요합니다.
- 큰 원본의 접근: 파일이나 리소스를 가리킬 때는 해당 클라이언트와 권한으로 열 수 있는 경로를 제공합니다. 서버 내부의
file://주소만 보내 놓고 원격 클라이언트가 읽을 수 있다고 가정하지 않습니다.
MCP 2025-11-25 도구 사양은 outputSchema, structuredContent, 텍스트와 resource_link 같은 결과 형식을 제공합니다. 구조화 JSON을 사용한다고 자동으로 작아지지는 않습니다. 같은 내용을 텍스트에도 복제하면 출력이 늘어날 수 있습니다. 또 tools/list의 nextCursor는 도구 목록의 페이지 구분입니다. 위 예시의 로그 페이지는 도구 호출 결과 안에서 직접 설계한 것입니다.
Anthropic의 MCP 코드 실행 설명은 모델이 읽기 전에 데이터를 처리하고 필요한 내용만 전달하는 방향을 제시합니다. 직접 적용하려면 실행 격리, 자원 제한과 관찰 수단도 필요합니다. 특정 사례의 절감 수치를 자신의 Claude Code 속도나 비용으로 옮겨 계산하지 마세요. 서버를 바꾸기 어렵다면 현재 도구가 제공하는 필터·상세 조회부터 사용합니다.
압축하거나 새 대화를 열 때 작업 상태를 남기세요
조회 형식을 줄여도 이미 쌓인 대화는 남습니다. /compact는 같은 대화를 요약하고, /clear는 빈 대화를 시작하며 프로젝트 메모리는 유지합니다. 둘의 차이는 Claude Code 명령어 안내에 나와 있습니다. 중요한 기록이 모두 손실 없이 보존된다고 가정하지 말고, 다시 확인할 수 있는 작업 메모를 먼저 남기세요.
배치 조사에서는 다음 정도의 메모로 작업을 이어갈 수 있습니다.
목표: batch-204 실패 원인을 구분하고 수정 후 확인 항목을 정한다.
범위: 2026-10-06 09:00–09:10 UTC의 오류 기록.
확인된 사실: 오류 37건, timeout 31건, invalid_payload 6건.
아직 미확인: timeout이 같은 요청에서 반복됐는지 여부.
원본: log-801과 log-926, 상세 조회에 필요한 작업 ID.
다음 행동: 대표 기록의 앞뒤 이벤트를 읽고 입력 항목을 확인한다.
유지할 접근: 배치 상태와 로그 조회 MCP.이 메모의 숫자와 위치는 위 예시에만 해당합니다. 실제 작업에서는 확인된 사실과 가설을 분리하고, 원본에 접근하는 데 필요한 식별자와 조건을 남깁니다. 암호나 토큰을 작업 메모에 붙여 넣을 필요는 없습니다.
/compact에 이어서 할 조사와 보존할 정보를 지정할 수 있습니다. 정리 후에는 원본 두 건을 다시 찾을 수 있는지, 남은 가설과 다음 행동이 유지됐는지 확인하세요. 같은 거대한 출력을 다시 받아 넣으면 곧 같은 압박이 생깁니다.
하위 에이전트로 별도 조사를 맡기는 방법도 있습니다. 각 에이전트는 별도 컨텍스트를 사용하지만 이미 부모 대화에 쌓인 출력까지 지우지는 않습니다. 조사 범위와 반환할 근거를 좁혀 맡기고, 부모에는 결론·기록 위치·미해결 사항을 돌려받는 방식이 유용합니다. 컨텍스트 관리 설명
새 대화마다 지침이 사라지거나 Context7 접속·버전이 문제라면 컨텍스트, 지속 지침과 MCP 연결을 구분하는 안내에서 해당 문제를 이어서 확인할 수 있습니다.
정리한 뒤에는 같은 작업으로 확인하세요
바꾼 항목을 하나씩 기록하고, 동일한 작업 ID와 기간으로 필요한 조회를 다시 수행합니다. 호출 전후 /context를 비교하되 다음 세 가지를 함께 확인하세요.
- 원본 오류와 필요한 상세 기록에 계속 접근할 수 있습니까?
- 요약의 범위와 건수가 실제 조회 조건과 맞고, 누락된 유형을 확인할 방법이 있습니까?
- 조사 결과가 수정이나 검증에 필요한 다음 행동으로 이어집니까?
사용량은 줄었는데 대표 기록이 사라졌다면 출력 설계를 보완합니다. 도구를 끈 뒤 원본을 읽을 수 없다면 다시 켭니다. 도구 정의의 부담이 그대로라면 검색 지원 경로와 강제 로딩 조건을 재확인합니다. 이 비교는 자신의 세션에서 얻는 확인이며 모든 모델·서버에 같은 개선율을 보장하지 않습니다.
서버를 몇 개까지 연결해도 괜찮나요?
고정된 수로 판단하기 어렵습니다. 이번 작업에서 필요한 접근인지, 결과를 필요한 범위로 받을 수 있는지, 사용량이 어느 시점에 늘어나는지를 보세요. 사용하지 않는 서버는 되돌릴 수 있게 끄고, 필요한 서버의 큰 출력은 별도로 줄입니다.
요약만 반환하면 중요한 오류를 놓치지 않나요?
그럴 수 있습니다. 그래서 요약에는 조회 범위, 오류별 건수, 대표 기록 ID와 추가 조회 방법을 함께 둡니다. 원본으로 돌아갈 수 없는 요약은 원인 조사에 충분하지 않습니다. 먼저 짧은 결과로 확인 대상을 고르고, 필요한 기록을 상세 조회하는 구조가 좋습니다.
정리 후 빨라졌으면 문제가 해결된 건가요?
체감 속도만으로는 판단하기 어렵습니다. 같은 범위의 자료를 확인해 원인을 구분하고, 원본 근거를 남기며, 다음 검증까지 이어질 수 있어야 합니다. 컨텍스트 공간과 필요한 정보를 함께 지키는 것이 정리의 완료 조건입니다.
참고 자료7
이 글이 링크한 외부 페이지를 본문에 나온 순서대로 정리했습니다. 마지막 업데이트: 2026년 10월 7일.
참고 자료7
이 글이 링크한 외부 페이지를 본문에 나온 순서대로 정리했습니다. 마지막 업데이트: 2026년 10월 7일.
- 1.공식 컨텍스트 설명code.claude.com/docs/en/context-window
- 2.명령어 안내code.claude.com/docs/en/commands
- 3.문제 해결 안내code.claude.com/docs/en/troubleshooting
- 4.Tool Search 설정 안내code.claude.com/docs/en/mcp
- 5.Claude API 오류 안내platform.claude.com/docs/en/api/errors
- 6.MCP 2025-11-25 도구 사양modelcontextprotocol.io/specification/2025-11-25/server/tools
- 7.Anthropic의 MCP 코드 실행 설명anthropic.com/engineering/code-execution-with-mcp





