Claude Code의 컨텍스트 소비를 98% 줄이는 MCP 서버

• Claude Code에서 외부 도구 호출 시 발생하는 대량의 원시 데이터가 컨텍스트 창을 빠르게 소모하는 문제를 해결
• Context Mode는 Claude Code와 도구 출력 사이에 위치해 데이터를 압축·필터링, 315KB를 5.4KB로 축소(98% 절감)
• 샌드박스 구조를 통해 각 실행을 격리하고, stdout만 컨텍스트에 포함해 로그·스냅샷 등의 원본 데이터 유출을 차단
• SQLite FTS5 기반 지식베이스로 마크다운 콘텐츠를 인덱싱하고, BM25 랭킹과 Porter stemming을 적용해 정확한 코드 블록 검색 지원
• 동일한 200K 토큰 한도에서 세션 지속 시간이 30분에서 3시간으로 늘어나며, AI 에이전트의 효율적 컨텍스트 관리 가능

문제점

• Claude Code의 MCP 도구 호출은 각 호출마다 원시 데이터를 200K 컨텍스트 창에 직접 덤프함
  • Playwright 스냅샷 56KB, GitHub 이슈 20개 59KB, 액세스 로그 45KB 등
  • 약 30분 사용 시 전체 컨텍스트의 40%가 소모됨
• MCP는 외부 도구 사용의 표준이 되었지만, 입력 정의와 출력 데이터 모두 컨텍스트를 채우는 구조적 한계 존재
• 81개 이상의 도구가 활성화된 상태에서 첫 메시지 전 이미 72%(143K 토큰)가 소비됨

Context Mode의 구조

• Claude Code와 도구 출력 사이에 위치한 MCP 서버로, 원시 데이터를 최소화해 전달
  • 315KB의 출력이 5.4KB로 줄어듦 (98% 감소)
• 각 execute 호출은 격리된 서브프로세스에서 실행되어 메모리·상태 공유 없이 독립 수행
  • stdout만 컨텍스트에 포함되고, 로그·API 응답·스냅샷 등은 샌드박스 내부에 유지
• 10개 언어 런타임 지원: JavaScript, TypeScript, Python, Shell, Ruby, Go, Rust, PHP, Perl, R
  • Bun 자동 감지로 JS/TS 실행 속도 3~5배 향상
• 인증 CLI(gh, aws, gcloud, kubectl, docker)는 환경 변수 상속 방식으로 자격 증명을 안전하게 전달

지식베이스(knowledge base)

• index 도구가 마크다운을 헤딩 단위로 분할하고 코드 블록을 그대로 유지한 채 SQLite FTS5 가상 테이블에 저장
• 검색 시 BM25 랭킹 알고리듬을 사용해 단어 빈도, 역문서 빈도, 문서 길이 정규화를 기반으로 관련성 계산
• Porter stemming 적용으로 “running”, “runs”, “ran”이 동일 어근으로 매칭
• search 호출 시 요약이 아닌 정확한 코드 블록과 헤딩 계층을 반환
• fetch_and_index는 URL을 가져와 HTML을 마크다운으로 변환 후 인덱싱, 원본 페이지는 컨텍스트에 포함되지 않음

성능 수치

• 11개 실제 시나리오(테스트 트리아지, TypeScript 오류 진단, git diff 검토 등)에서 모두 출력 1KB 이하 유지
  • Playwright 스냅샷: 56KB → 299B
  • GitHub 이슈(20개): 59KB → 1.1KB
  • 액세스 로그(500건): 45KB → 155B
  • CSV 분석(500행): 85KB → 222B
  • Git 로그(153커밋): 11.6KB → 107B
  • 리포지토리 조사(subagent): 986KB → 62KB (5회 호출 vs 37회)
• 전체 세션 기준 315KB → 5.4KB로 축소, 세션 지속 시간 30분 → 3시간
• 45분 후 남은 컨텍스트: 기존 60% → 99%

설치 및 사용

• Plugin Marketplace를 통한 자동 라우팅 훅 및 슬래시 명령 지원
• MCP 전용 설치도 가능
• Claude Code 재시작 후 바로 사용 가능

실제 변화

• 사용 방식 변경 없이 PreToolUse 훅이 자동으로 출력 라우팅
• 서브에이전트는 batch_execute를 기본 도구로 사용
• Bash 서브에이전트는 general-purpose로 업그레이드되어 MCP 도구 접근 가능
• 결과적으로 컨텍스트 창이 더 이상 빠르게 채워지지 않음, 동일 토큰으로 더 긴 세션 유지 가능

개발 배경

• MCP Directory & Hub 운영 중 모든 MCP 서버가 원시 데이터를 컨텍스트에 덤프하는 공통 패턴을 발견
• Cloudflare의 Code Mode가 도구 정의를 압축한 것에서 착안, 출력 데이터 압축 방향으로 확장
• Claude Code 세션에서 6배 더 오래 작업 가능함을 확인 후 MIT 라이선스로 오픈소스 공개
• GitHub: mksglu/claude-context-mode