새소식
300x250
AI/MCP
Claude Code MCP 토큰 최적화 고민해보기(MCP 토큰 최적화에 대한 고찰 글)
- -
728x90
안녕하세요. 갓대희 입니다.
오늘은 Claude Code MCP 토큰 최적화에 대해 고민해보고자 한다.
다음과 같은 글이 가장 큰 영감이 되었다.
https://www.anthropic.com/engineering/advanced-tool-use
AI 에이전트 활용에서 토큰 효율성은 비용 절감과 작업 정확도에 직결되는 핵심 요소다.
Claude Code에서 MCP(Model Context Protocol) 서버를 여러 개 연결하면 강력한 기능을 활용할 수 있지만, 동시에 심각한 토큰 낭비 문제가 발생한다.
Anthropic 공식 자료에 따르면, 5개 MCP 서버 설정만으로도 약 55,000 토큰이 대화 시작 전에 소비될 수 있다.
1. "컨텍스트가 도구로 가득 차면?" - MCP 토큰 문제
핵심 아이디어: 즉시 로드 vs 지연 로드
AI 에이전트의 도구 로딩 방식을 이해해보자:
| 즉시 로드 (Context Window) - 크기: 200K 토큰 - 세션 시작 시 항상 로드됨 - 도구 정의도 여기에 포함! |
지연 로드 (Deferred Tools) - 필요할 때만 로드되는 방식 - 토큰 소비 없이 대기 - defer_loading의 목표! |
💡 해결책: 도구를 지연 로드로 전환하면 → 컨텍스트 공간 확보 → 토큰 절약!
MCP 서버를 Claude Code에 연결하면, 해당 서버의 모든 도구 정의(tool definitions)가 세션 시작 시점에 컨텍스트로 로드된다. AI가 어떤 도구를 사용할 수 있는지 알아야 하기 때문인데, 문제는 이 도구 정의들이 상당한 토큰을 소비한다는 점이다.
Anthropic 공식 발표
"5개 서버 설정(GitHub 35개, Slack 11개 등)으로 총 58개 도구가 약 55K 토큰을 소비합니다. Jira(약 17K 토큰) 같은 서버를 추가하면 빠르게 100K+ 토큰 오버헤드에 도달합니다. 내부적으로 도구 정의가 134K 토큰을 소비하는 경우도 확인했습니다."
출처: Anthropic Engineering Blog - Advanced Tool Use
"5개 서버 설정(GitHub 35개, Slack 11개 등)으로 총 58개 도구가 약 55K 토큰을 소비합니다. Jira(약 17K 토큰) 같은 서버를 추가하면 빠르게 100K+ 토큰 오버헤드에 도달합니다. 내부적으로 도구 정의가 134K 토큰을 소비하는 경우도 확인했습니다."
출처: Anthropic Engineering Blog - Advanced Tool Use
토큰 소비 현황 예시
| 구성 요소 | 토큰 소비량 | 비율 (200K 기준) |
|---|---|---|
| MCP 도구 정의 (즉시 로드) | ~40K | 20% |
| 시스템 도구 | ~23K | 11.5% |
| 메모리 파일 | ~36K | 18% |
| 합계 | ~100K | 50% |
※ 이 수치는 GitHub Issue #7336에서 사용자가 보고한 예시이며, 실제 환경에 따라 달라질 수 있다. (출처)
실제 사용자 사례 (GitHub Issue #12836)
| 환경 | MCP 서버 ~20-30개 도구 |
| 총 토큰 소비 | 73.9k 토큰 |
| 미사용 도구 토큰 | 53k 토큰 (72%!) |
⚠️ 실제 환경에서 72%의 토큰이 사용하지 않는 도구에 낭비되고 있습니다!
출처: GitHub Issue #12836
2. MCP 서버 선택적 활성화 / 비활성화 하기
✅ 공식 지원 기능
아래 방법들은 Claude Code CLI 공식 문서에서 확인된 기능으로, 지금 바로 적용할 수 있다.
실험적이거나 비공식적인 방법(ENABLE_EXPERIMENTAL_MCP_CLI 등)은 섹션 7에서 별도로 다룬다.
아래 방법들은 Claude Code CLI 공식 문서에서 확인된 기능으로, 지금 바로 적용할 수 있다.
실험적이거나 비공식적인 방법(ENABLE_EXPERIMENTAL_MCP_CLI 등)은 섹션 7에서 별도로 다룬다.
defer_loading이 Claude Code CLI에 정식 지원될 때까지, 다음 방법들로 토큰 사용량을 직접 최적화할 수 있다. 모두 공식 문서에서 확인된 기능이다.
방법 1 : MCP 서버 선택적 활성화/비활성화
현재 작업에 필요하지 않은 MCP 서버를 비활성화하여 즉시 토큰을 절약할 수 있다.
# Claude Code 내에서 MCP 관리
/mcp # MCP 서버 목록 및 상태 확인
/context # 현재 컨텍스트 토큰 사용량 확인
# 세션 내에서 특정 서버 비활성화/활성화
/mcp disable [server-name] # 지연 로드로 전환 (토큰 절약)
/mcp enable [server-name] # 즉시 로드로 전환
방법 2: --tools 및 --allowedTools 옵션으로 도구 제한
CLI 실행 시 특정 도구만 활성화하여 불필요한 도구 로딩을 방지한다.
주의:
--tools 옵션은 --print(-p) 모드에서만 작동한다. 대화형 세션에서는 --allowedTools/--disallowedTools를 사용하자.# --tools (--print 모드 전용)
# 기본 도구만 사용 (MCP 도구 제외) - 비대화형 출력
claude -p --tools "Bash,Edit,Read,Write" "작업 내용"
# 모든 도구 비활성화 (간단한 질문용)
claude -p --tools "" "간단한 질문"# --allowedTools / --disallowedTools (대화형 모드에서도 작동)
# 특정 도구만 허용 (패턴 지원)
claude --allowedTools "Bash(git log:*)" "Read"
# 특정 도구 차단
claude --disallowedTools "mcp__server__dangerous_tool"출처: Claude Code CLI Usage Documentation (v2.0.69 검증됨)
방법 3: MCP 구성 파일 분리
프로젝트나 작업 유형별로 다른 MCP 구성을 사용한다.
# 작업별 MCP 구성 파일 분리
# 최소한의 MCP만 로드 (바닥에 많이 두기)
claude --mcp-config ./mcp-minimal.json
# 프론트엔드 작업용 MCP 구성
claude --mcp-config ./mcp-frontend.json
# 지정된 MCP만 사용 (다른 구성 무시)
claude --strict-mcp-config --mcp-config ./mcp-backend.json
방법 4: MCP 도구 통합 및 설명 축소
Scott Spence의 최적화 사례에 따르면, 유사한 도구를 통합하고 설명을 간소화하는 것만으로도 60% 토큰 감소를 달성할 수 있다.
도구 통합 예시
Before: tavily_search, brave_search, perplexity_search (3개 도구)
After: web_search (provider 파라미터로 구분) - 1개 도구
결과: 20개 도구 → 8개 도구, 14,214 토큰 → 5,663 토큰 (60% 감소)
출처: Scott Spence 블로그
Before: tavily_search, brave_search, perplexity_search (3개 도구)
After: web_search (provider 파라미터로 구분) - 1개 도구
결과: 20개 도구 → 8개 도구, 14,214 토큰 → 5,663 토큰 (60% 감소)
출처: Scott Spence 블로그
방법 5: MAX_MCP_OUTPUT_TOKENS 설정
MCP 도구의 출력 토큰 한도를 조절하여 대용량 출력으로 인한 컨텍스트 낭비를 방지한다.
# 환경 변수로 MCP 출력 제한
# 기본값: 25,000 토큰
export MAX_MCP_OUTPUT_TOKENS=15000
# 또는 실행 시 지정
MAX_MCP_OUTPUT_TOKENS=15000 claude
방법 6: mcp-cli로 세션 없이 MCP 도구 직접 호출 (v2.0.69+)
mcp-cli의 핵심 가치: Claude 세션을 시작하지 않고도 MCP 도구를 직접 호출할 수 있다. 세션 시작 시 발생하는 도구 정의 로드 토큰을 완전히 회피하는 방법이다.
토큰 절약 원리: 세션 vs 직접 호출
Claude 세션으로 조회claude → "Linear 이슈 보여줘"→ linear-server 22개 도구 정의 로드 → ~5,000~10,000 토큰 소비 |
mcp-cli 직접 호출mcp-cli call linear-server/list_issues '{}'→ Claude 세션 없음 → 토큰 소비 0 |
# mcp-cli 직접 호출로 토큰 절약하기
# 1. 도구 스키마 확인 (파라미터 이름/타입 확인)
mcp-cli info linear-server/list_issues
# 2. 직접 호출 (Claude 세션 없이!)
mcp-cli call linear-server/list_issues '{"limit": 5, "assignee": "me"}'
# 3. 특정 이슈 조회
mcp-cli call linear-server/get_issue '{"id": "ABC-123"}'
# 4. 이슈 생성도 가능
mcp-cli call linear-server/create_issue '{"title": "버그 수정", "teamId": "TEAM-1"}'mcp-cli 직접 호출이 적합한 경우:
- 단순 조회 작업: 이슈 확인, 문서 조회, 상태 체크 등
- 일회성 작업: 데이터 한 번 가져오기
- 자동화 스크립트: CI/CD, cron job에서 MCP 도구 사용
- MCP 도구 테스트/디버깅: 세션 오버헤드 없이 빠른 테스트
간접 절약: 현황 파악 후 서버 비활성화
AI 대화가 필요한 복잡한 작업에서는 claude mcp list로 현황을 파악하고, 불필요한 서버를 비활성화하자.
# 간접 절약 워크플로우
# 1단계: 서버별 도구 수 확인
claude mcp list
# linear-server: 22 tools ← 많음!
# 2단계: Claude 세션에서 비활성화
/mcp disable linear-server # 세션 내에서 토큰 절약
# 또는 처음부터 최소 구성으로 시작
claude --strict-mcp-config --mcp-config ./mcp-minimal.json핵심 요약: 단순 조회는 mcp-cli call로 직접 호출(토큰 0), 복잡한 AI 대화가 필요하면 /mcp disable로 불필요한 서버 비활성화. 상황에 맞게 두 방식을 조합하자!
3. 최적화 방법 효과 비교
| 방법 | 예상 토큰 감소 | 난이도 | 즉시 적용 |
|---|---|---|---|
| MCP 서버 비활성화 | 서버당 10K+ | ⭐ | ✅ |
| --tools 옵션 사용 | 20-50% | ⭐⭐ | ✅ |
| MCP 구성 파일 분리 | 30-60% | ⭐⭐ | ✅ |
| 도구 통합/설명 축소 | 40-60% | ⭐⭐⭐ | MCP 수정 필요 |
| mcp-cli 직접 호출 (세션 없이 MCP 도구 사용, v2.0.69+) |
100% (세션 토큰 0) |
⭐ | ✅ |
| claude mcp + /mcp disable (현황 파악 후 수동 비활성화) |
서버당 10K+ (간접 지원) |
⭐ | ✅ |
| Tool Search Tool (API) | 85% | ⭐⭐⭐ | API 직접 호출만 |
4. Tool Search Tool (API 베타)
📡 API 직접 호출 전용
이 섹션은 Anthropic API를 직접 호출하는 개발자를 위한 내용이다.
Claude Code CLI(
이 섹션은 Anthropic API를 직접 호출하는 개발자를 위한 내용이다.
Claude Code CLI(
claude 명령어) 사용자는 섹션 2의 수동 최적화 전략을 먼저 적용하자.핵심 포인트: API vs CLI 구분
| Anthropic API | Tool Search Tool 베타 지원 |
| Claude Code CLI | 아직 미지원 (Feature Request 상태) |
Anthropic은 2025년 11월, 이 문제를 해결하기 위한 Advanced Tool Use 베타 기능을 발표했다. 핵심 아이디어는 모든 도구를 미리 로드하는 대신, 필요할 때만 동적으로 도구를 발견하는 것이다.
지연 로드 활성화 = defer_loading: true
defer_loading: true를 설정하면 해당 도구는:
세션 시작 시 컨텍스트에 로드되지 않음
AI가 필요하다고 판단할 때만 동적으로 로드됨
결과: 85% 토큰 절약!
Tool Search Tool 핵심 원리
"Tool Search Tool은 Claude가 모든 도구 정의를 미리 로드하지 않고 필요에 따라 동적으로 도구를 발견할 수 있게 합니다. 도구에
Regex 패턴 매칭: Beta ID에
출처: Anthropic Engineering Blog
"Tool Search Tool은 Claude가 모든 도구 정의를 미리 로드하지 않고 필요에 따라 동적으로 도구를 발견할 수 있게 합니다. 도구에
defer_loading: true를 표시하면 해당 도구는 초기에 로드되지 않고, Claude가 검색을 수행할 때만 컨텍스트로 확장됩니다." Regex 패턴 매칭: Beta ID에
regex가 포함된 이유는 도구 검색 시 정규표현식 패턴 매칭을 지원하기 때문입니다. 도구명, 설명, 키워드를 regex로 유연하게 검색할 수 있습니다. 출처: Anthropic Engineering Blog
Anthropic 벤치마크
| 지표 | 기존 방식 (모두 즉시 로드) |
Tool Search Tool (지연 로드) |
개선율 |
|---|---|---|---|
| 토큰 사용량 | ~77K | ~8.7K | 85% 감소 |
| Opus 4 정확도 | 49% | 74% | +25%p |
| Opus 4.5 정확도 | 79.5% | 88.1% | +8.6%p |
| 컨텍스트 윈도우 보존 | 122,800 토큰 (68,500 도구 정의 소비) |
191,300 토큰 (95% 보존) |
+68,500 토큰 |
※ Anthropic 공식 벤치마크 결과다. (출처)
추가 베타 기능: Programmatic Tool Use
Anthropic은 Tool Search Tool 외에도 Programmatic Tool Use 베타 기능을 제공한다.
이 기능은 Claude가 Python 코드를 작성하여 샌드박스 컨테이너에서 실행하는 방식이다.
- Python 코드로 도구 호출 → 중간 tool_use 호출 없이 최종 결과만 반환
- 에러 발생 시 Claude가 자동으로 복구 코드 작성 시도
- Python 내장 패키지 생태계 활용 가능
- 19+ 추론 패스 → 단일 호출로 통합 (공식 벤치마크)
- 결과: 토큰 37% 추가 절감 (도구 호출 오버헤드 제거)
| 기능 | 베타 ID | 토큰 절감 |
| Tool Search Tool ※ Regex 패턴 매칭 지원 |
tool_search_tool_regex_20251119 |
85% 감소 |
| Programmatic Tool Use | code_execution_20250825 |
+37% 추가 감소 |
| Tool Use Examples | 별도 ID 없음( input_examples 파라미터로 통합) |
정확도 72%→90% |
| 전체 기능 조합 | - | 토큰 90%+ 절감 + 정확도 향상 |
출처: Anthropic Engineering Blog - 공식 Beta ID 정보
추가 기능: Tool Use Examples
복잡한 도구 사용 시나리오에서 정확도를 72%에서 90%로 향상시키는 기능이다.
별도 Beta ID가 없다. 개별 도구 정의에 input_examples 파라미터를 추가하는 방식이다.
| Beta ID | 별도 ID 없음 - 도구 스키마에 input_examples로 통합 |
| 정확도 향상 | 72% → 90% (+18%p) |
| 권장 사용 조건 | 복잡한 중첩 구조, 도메인별 특화 API |
| 적용 방법 | 도구 정의의 input_examples 필드에 예시 전달 |
💡 토큰 절감과 정확도 향상을 동시에! Tool Search Tool로 토큰을 줄이고, Tool Use Examples로 정확도를 높이세요.
기능별 권장 사용 조건
| 기능 | 권장 사용 조건 | 주요 효과 |
|---|---|---|
| Tool Search Tool | • 도구 정의가 10K+ 토큰 소비 • 10개 이상의 도구 사용 |
컨텍스트 95% 보존, 토큰 85% 감소 |
| Programmatic Tool Use | • 3개 이상의 의존적 도구 호출 • 복잡한 다단계 워크플로우 |
19+ 추론 패스 → 1회, 토큰 37% 추가 감소 |
| Tool Use Examples | • 복잡한 중첩 구조 API • 도메인 특화 매개변수 |
정확도 72% → 90% (+18%p) |
💡 조합 사용 권장: 위 조건에 해당하면 여러 기능을 함께 사용하여 최대 90%+ 토큰 절감과 정확도 향상을 동시에 달성할 수 있다.
API 직접 호출 예시 (Python SDK)
import anthropic
client = anthropic.Anthropic()
# Tool Search Tool + MCP 통합 (API 레벨)
response = client.messages.create(
model="claude-sonnet-4-5-20250929", # Claude Sonnet 4.5
betas=[
"advanced-tool-use-2025-11-20", # Tool Search 베타
# "mcp-client-2025-11-20" # 별도 확인 필요
],
mcp_toolset={
"servers": [
{"url": "https://mcp.example.com/github"},
{"url": "https://mcp.example.com/slack"}
],
"default_config": {
"defer_loading": True
}
},
max_tokens=1024,
messages=[{"role": "user", "content": "..."}]
)⚠️ 이 코드는 API를 직접 호출할 때 사용한다. Claude Code CLI에서는 사용할 수 없다.
Anthropic 권장 설정
Anthropic은 3~5개의 가장 자주 사용하는 도구는 항상 로드(
(출처: Anthropic Engineering Blog)
Anthropic은 3~5개의 가장 자주 사용하는 도구는 항상 로드(
defer_loading: false)하고, 나머지는 지연 로딩(defer_loading: true)할 것을 권장한다. 이렇게 하면 일반적인 작업에는 즉시 접근하면서도 토큰을 절약할 수 있다. (출처: Anthropic Engineering Blog)
5. CLI MCP 관리 도구 (v2.0.69+)
두 가지 CLI 도구
Claude Code 최신 버전(내가 테스트 한건 2.0.69)부터 MCP 관리를 위한 두 가지 CLI 도구가 제공된다:
Claude Code 최신 버전(내가 테스트 한건 2.0.69)부터 MCP 관리를 위한 두 가지 CLI 도구가 제공된다:
| 도구 | 핵심 가치 | 토큰 절약 |
mcp-cli call |
세션 없이 MCP 도구 직접 호출 | 100% (세션 토큰 0) |
claude mcp list |
서버 현황 + 도구 수 확인 | 간접 (비활성화 판단용) |
mcp-cli info |
도구 스키마/파라미터 확인 | call 전 필수 확인 |
💡 핵심: mcp-cli call이 토큰 절약의 핵심. 단순 조회 작업은 Claude 세션 없이 직접 호출하면 토큰 소비가 0이다!
6. Claude Code CLI 지원 현황 (2025년 12월 기준)
중요: Claude Code CLI에서는 defer_loading 미지원
Tool Search Tool과
Claude Code CLI(터미널에서
GitHub에서 관련 기능 요청이 진행 중입니다:
• Issue #7336: Lazy Loading for MCP Servers (Feature Request)
• Issue #12836: Support Tool Search and Programmatic Tool Use betas
Tool Search Tool과
defer_loading 기능은 Anthropic API 레벨에서만 베타로 제공됩니다. Claude Code CLI(터미널에서
claude 명령어로 사용하는 도구)에서는 2025년 12월 현재 이 기능을 직접 사용할 수 없습니다. GitHub에서 관련 기능 요청이 진행 중입니다:
• Issue #7336: Lazy Loading for MCP Servers (Feature Request)
• Issue #12836: Support Tool Search and Programmatic Tool Use betas
기능 지원 현황 요약
| 기능 | Anthropic API | Claude Code CLI |
| Tool Search Tool | ✅ 베타 | ⚠️ 부분 지원* |
| defer_loading 옵션 | ✅ 베타 | ⚠️ 부분 지원* |
| ENABLE_EXPERIMENTAL_MCP_CLI | - | ⚠️ 실험적 지원 (on-demand 스키마 로드) |
| MCP 서버 활성화/비활성화 | - | ✅ 지원 |
| --tools 옵션으로 도구 제한 | - | ✅ 지원 |
| MCP 구성 파일 분리 | - | ✅ 지원 |
| mcp-cli (도구 조회/호출) | - | ✅ 지원 |
| claude mcp (서버 설정 관리) | - | ✅ 지원 |
* 부분 지원: ENABLE_EXPERIMENTAL_MCP_CLI=true 설정 시 on-demand 스키마 로드로 유사한 토큰 절감 효과를 얻을 수 있다. 단, Tool Search Tool(검색 기반 도구 발견)과는 다른 메커니즘이며, 공식 문서에 명시되지 않은 실험적 기능이다. 자세한 비교는 섹션 7 참고.
7. 실험적 기능 : ENABLE_EXPERIMENTAL_MCP_CLI
⚠️ 비공식/실험적 기능
이 섹션의 내용은 Anthropic의 공식 문서에 명시되지 않은 실험적 기능이다.
"EXPERIMENTAL"이 이름에 포함되어 있으며, 향후 변경되거나 제거될 수 있다.
권장 사항: 먼저 섹션 2의 공식 최적화 방법을 적용하고,
추가 최적화가 필요한 경우에만 이 기능을 참고하자. 테스트 환경에서 먼저 시도할 것을 권장한다.
이 섹션의 내용은 Anthropic의 공식 문서에 명시되지 않은 실험적 기능이다.
"EXPERIMENTAL"이 이름에 포함되어 있으며, 향후 변경되거나 제거될 수 있다.
권장 사항: 먼저 섹션 2의 공식 최적화 방법을 적용하고,
추가 최적화가 필요한 경우에만 이 기능을 참고하자. 테스트 환경에서 먼저 시도할 것을 권장한다.
| 설정 | MCP 도구 스키마 처리 | 컨텍스트 영향 |
|---|---|---|
| OFF (기본값) |
모든 MCP 도구의 전체 스키마가 시스템 프롬프트에 즉시 로드 |
많은 토큰 소비 가능 (서버/도구 수에 따라) |
| ON (=true) |
도구 이름 목록만 로드 스키마는 mcp-cli info로 on-demand 조회 |
많은 도큰 절약 (도구 이름만 포함) |
⚠️ 참고: 이 동작은 직접 테스트로 확인한 결과이며, Anthropic의 공식 문서에는 아직 명시되지 않았다.
GitHub Issue #12836에서 요청 중인 Tool Search Tool과는 다른 메커니즘이지만, 유사한 토큰 절감 효과를 제공한다. (아래 비교표 참고)
설정 방법 (OS별/셸별 가이드)
macOS / Linux
방법 1: 일회성 실행 (현재 세션만)
# Zsh / Bash 공통
export ENABLE_EXPERIMENTAL_MCP_CLI=true
claude
# 또는 한 줄로 (설정 없이 바로 테스트)
ENABLE_EXPERIMENTAL_MCP_CLI=true claude방법 2: 영구 설정
| 셸 | 설정 파일 | 추가할 내용 |
|---|---|---|
| Zsh (macOS 기본) |
~/.zshrc |
export ENABLE_EXPERIMENTAL_MCP_CLI=true |
| Bash | ~/.bashrc |
export ENABLE_EXPERIMENTAL_MCP_CLI=true |
| Fish | ~/.config/fish/config.fish |
set -gx ENABLE_EXPERIMENTAL_MCP_CLI true |
# Zsh 영구 설정 예시
echo 'export ENABLE_EXPERIMENTAL_MCP_CLI=true' >> ~/.zshrc
source ~/.zshrc
# Bash 영구 설정 예시
echo 'export ENABLE_EXPERIMENTAL_MCP_CLI=true' >> ~/.bashrc
source ~/.bashrc
# Fish 영구 설정 예시
echo 'set -gx ENABLE_EXPERIMENTAL_MCP_CLI true' >> ~/.config/fish/config.fish
source ~/.config/fish/config.fishWindows
PowerShell
# 일회성 실행 (현재 세션만)
$env:ENABLE_EXPERIMENTAL_MCP_CLI = "true"
claude
# 영구 설정 (사용자 환경변수)
[Environment]::SetEnvironmentVariable("ENABLE_EXPERIMENTAL_MCP_CLI", "true", "User")
# 새 PowerShell 창을 열어야 적용됨CMD (명령 프롬프트)
:: 일회성 실행 (현재 세션만)
set ENABLE_EXPERIMENTAL_MCP_CLI=true
claude
:: 영구 설정 (사용자 환경변수)
setx ENABLE_EXPERIMENTAL_MCP_CLI true
:: 새 CMD 창을 열어야 적용됨💡 GUI로 설정: 시스템 속성 → 고급 → 환경 변수 → 사용자 변수에 ENABLE_EXPERIMENTAL_MCP_CLI = true 추가
설정 확인 방법
# macOS/Linux
echo $ENABLE_EXPERIMENTAL_MCP_CLI
# 출력: true
# Windows PowerShell
echo $env:ENABLE_EXPERIMENTAL_MCP_CLI
# 출력: true
# Windows CMD
echo %ENABLE_EXPERIMENTAL_MCP_CLI%
# 출력: true설정 해제 (원복) 방법
| 환경 | 영구 설정 해제 방법 |
|---|---|
| Zsh/Bash | ~/.zshrc 또는 ~/.bashrc에서 해당 줄 삭제 후source ~/.zshrc 또는 터미널 재시작 |
| Fish | ~/.config/fish/config.fish에서 해당 줄 삭제 후set -e ENABLE_EXPERIMENTAL_MCP_CLI 실행 |
| Windows PS | [Environment]::SetEnvironmentVariable("ENABLE_EXPERIMENTAL_MCP_CLI", $null, "User") |
| Windows CMD | setx ENABLE_EXPERIMENTAL_MCP_CLI "" 또는 GUI에서 삭제 |
💡 설정 후 새 Claude Code 세션을 시작해야 적용된다. /context 명령으로 MCP tools 토큰 변화를 확인할 수 있다.
GitHub Issue #12836: 커뮤니티가 요청하는 기능
커뮤니티에서는 Anthropic API의 Tool Search Tool 베타(defer_loading: true)를 Claude Code CLI에도 구현해달라고 요청 중이다. (Issue #12836, 👍 46개)
Issue에서 보고된 실제 사례:
- 20-30개 도구 MCP 서버: 73.9K 토큰 소비
- 미사용 도구 3개만으로: 53K 토큰 (전체의 72%)
- Tool Search Tool 적용 시: 85% 토큰 감소
- 정확도 향상: Opus 4 (49%→74%), Opus 4.5 (79.5%→88.1%)
⚠️ Tool Search Tool vs ENABLE_EXPERIMENTAL_MCP_CLI 차이점
| 구분 | Tool Search Tool (API 베타) | ENABLE_EXPERIMENTAL_MCP_CLI |
|---|---|---|
| 도구 발견 방식 | 검색 기반 Claude가 필요한 도구를 자동 검색 |
목록 기반 모든 도구 이름이 표시됨 |
| 스키마 로딩 | 검색된 도구만 자동 로드 | mcp-cli info로 수동 호출 |
| 토큰 절감 | 85% (공식 발표) | 상당량 (테스트 필요) |
결론: ENABLE_EXPERIMENTAL_MCP_CLI는 Tool Search Tool의 완전한 구현이 아니라, 스키마 로딩을 지연시켜 유사한 토큰 절감 효과를 제공하는 별도의 메커니즘이다.
⚠️ 주의사항 및 트레이드오프
| 실험적 기능 | 이 환경변수는 "EXPERIMENTAL"이 이름에 포함되어 있다. 향후 버전에서 변경되거나 제거될 수 있으므로 주의가 필요하다. |
| 추가 호출 필요 | 설정 ON 시 Claude가 도구를 사용하기 전에 mcp-cli info를 호출해야 한다.즉, 약간의 추가 단계가 생기지만 전체 토큰은 절약된다. |
| 공식 문서 부재 | Anthropic 공식 문서에 이 동작이 명시되어 있지 않다. 테스트 결과 기반 분석이므로 환경에 따라 다를 수 있다. |
3-1. mcp-cli call: 세션 없이 도구 직접 호출
mcp-cli의 핵심 가치는 call 명령어다. Claude 세션을 시작하지 않고 MCP 도구를 직접 호출하여 도구 정의 로드 토큰을 완전히 회피한다.
mcp-cli 주요 명령어
# MCP 서버 목록 확인
mcp-cli servers
# 사용 가능한 도구 목록 확인
mcp-cli tools [server]
# 도구 이름/설명에서 검색
mcp-cli grep <pattern>
# 도구의 상세 스키마 정보 확인
mcp-cli info <server>/<tool>
# 도구 호출 (JSON 파라미터)
mcp-cli call <server>/<tool> '{"param": "value"}'
# MCP 리소스 목록 확인
mcp-cli resources [server]
# MCP 리소스 읽기
mcp-cli read <server>/<resource>직접 테스트 결과 (2025년 12월 16일, macOS)
| Claude Code 버전 | 2.0.69 |
| 테스트 명령어 | 결과 |
which mcp-cli |
✅ aliased to claude --mcp-cli |
mcp-cli --help |
✅ 정상 출력 |
mcp-cli servers |
✅ 서버 목록 표시 |
mcp-cli tools |
✅ 도구 목록 표시 |
mcp-cli info <tool> |
✅ 스키마 정보 표시 |
mcp-cli grep <pattern> |
✅ 검색 작동 |
mcp-cli 활용 예시
# 1. 연결된 MCP 서버 확인
$ mcp-cli servers
sequential-thinking - connected (tools)
linear-server - connected (tools)
ide - connected (tools)
# 2. linear-server의 도구 목록 확인
$ mcp-cli tools linear-server
linear-server/list_issues
linear-server/get_issue
linear-server/create_issue
...
# 3. 도구 스키마 확인 (호출 전 필수!)
$ mcp-cli info linear-server/list_issues
Tool: linear-server/list_issues
Input Schema: { "limit": number, "assignee": string, ... }
# 4. 도구 호출
$ mcp-cli call linear-server/list_issues '{"limit": 5, "assignee": "me"}'⚠️ 중요: 도구 호출 전에 반드시 mcp-cli info로 스키마를 확인하자. 파라미터 이름과 타입이 예상과 다를 수 있다!
3-2. claude mcp: 서버 설정 관리
claude mcp는 MCP 서버 구성을 관리하는 서브커맨드다. 서버 추가/삭제, 연결 상태 확인 등 설정 관리에 특화되어 있다.
claude mcp 주요 명령어
# MCP 서버 목록 및 연결 상태 확인
claude mcp list
# 새 MCP 서버 추가 (transport 유형별)
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
claude mcp add --transport sse asana https://mcp.asana.com/sse
claude mcp add --transport stdio my-server -- npx my-mcp-server
# MCP 서버 제거
claude mcp remove <server-name>
# 특정 서버 설정 조회
claude mcp get <server-name>
# 고급: Claude Desktop에서 서버 가져오기 (Mac/WSL)
claude mcp add-from-claude-desktopclaude mcp list 실행 예시
$ claude mcp list
╭─────────────────────────────────────────────────────────────────╮
│ MCP Servers │
├─────────────────────────────────────────────────────────────────┤
│ ✓ Connected │
│ sequential-thinking (project) 1 tool │
│ linear-server (project) 22 tools │
│ ide (project) 2 tools │
├─────────────────────────────────────────────────────────────────┤
│ ⚠ Needs authentication - run `claude mcp auth <server-name>` │
│ cloudflare (user) │
╰─────────────────────────────────────────────────────────────────╯💡 활용 팁: 서버별 도구 수를 파악하여, 많은 도구를 가진 서버를 필요시에만 활성화하면 토큰을 절약할 수 있다!
mcp-cli vs claude mcp: 언제 무엇을 사용할까?
| 상황 | 사용할 도구 |
| 어떤 도구가 있는지 찾고 싶을 때 | mcp-cli tools, mcp-cli grep |
| 도구 스키마/사용법 확인 | mcp-cli info <tool> |
| 세션 외부에서 도구 직접 호출 | mcp-cli call <tool> '{...}' |
| 서버 연결 상태 및 도구 수 확인 | claude mcp list |
| 새 MCP 서버 추가/제거 | claude mcp add/remove |
| 토큰 최적화를 위한 서버 파악 | claude mcp list → /mcp disable |
8. 커뮤니티 대안: MCP Proxy & Gateway
공식 CLI 지원을 기다리는 동안, 커뮤니티에서 개발한 대안 솔루션들이 있다. GitHub Issue #12836에서 공유된 정보.
커뮤니티 개발 도구 (참고용)
3. Docker MCP Toolkit
Docker 기반 MCP 도구 통합 솔루션. Issue #12836 댓글에서 saintmac이 공유한 프로젝트다.
🔗 github.com/docker/labs-ai-tools-for-devs4. TF-IDF 기반 도구 검색 (제안됨)
사용자 메시지를 분석하여 관련 도구만 동적으로 로드하는 방식. 커뮤니티에서 제안된 아이디어다.
상태: 아이디어 단계 (구현체 없음)⚠️ 위 도구들은 커뮤니티 프로젝트이며, Anthropic 공식 지원이 아니다.
사용 전 보안 검토와 테스트를 권장한다.
9. 향후 전망 (추정)
GitHub에서 진행 중인 기능 요청과 커뮤니티 활동을 기반으로, Claude Code CLI에서도 다음 기능들이 지원될 것으로 예상된다:
예상되는 향후 지원 기능
- settings.json에서 defer_loading 설정: MCP 서버별 지연 로딩 옵션
- 키워드 기반 자동 로딩: 대화 내용 분석 후 필요한 도구만 로드
- 레지스트리 기반 Lazy Loading: 경량 레지스트리로 95% 토큰 절감
⚠️ 이 내용은 GitHub Issue #7336, #12836의 제안을 기반으로 한 추정이며, Anthropic의 공식 로드맵이 아니다.
Anthropic 팀 응답 (Issue #12836)
jspahrsummers (Anthropic 직원)이 Issue #12836에서 "Stay tuned"라고 응답했다.
이는 CLI 지원이 공식적으로 검토/개발 중임을 시사한다. (2025년 12월 기준)
커뮤니티 제안: settings.json 구조 (⚠️ 추정)
Issue #7336과 #12836에서 제안된 Claude Code CLI용 설정 구조다. 아직 지원되지 않는다.
// settings.json 또는 .claude/settings.json (미래 지원 예상)
{
"mcpServers": {
"github": {
"command": "...",
"defer_loading": true, // 지연 로드 (Issue #12836)
"keywords": ["git", "pr", "issue", "commit"], // Issue #7336
"allowed_callers": ["Claude Code"] // 특정 도구만 노출 (Issue #12836 댓글)
},
"slack": {
"command": "...",
"defer_loading": true, // 지연 로드
"keywords": ["message", "channel", "slack"]
},
"filesystem": {
"command": "...",
"defer_loading": false // 즉시 로드
}
}
}⚠️ 이 구조는 커뮤니티 제안이며, 현재 Claude Code CLI에서 지원되지 않는다.
• defer_loading: Issue #12836 핵심 요청 → API 공식 지원 (Anthropic Blog)
• keywords: Issue #7336 제안
• allowed_callers: Issue #12836 댓글 제안 → API 공식 지원 (Programmatic Tool Use)
CLI 지원 시 형식이 달라질 수 있다.
자주 묻는 질문 ❓
Q: "지연 로드(defer_loading)"가 정확히 무슨 의미인가요?
A: AI가 사용할 수 있는 도구들을 세션 시작 시 모두 컨텍스트에 로드(즉시 로드)하는 대신, 필요할 때만 동적으로 로드(지연 로드)하는 방식이다.
defer_loading: true를 설정하면 해당 도구는 초기에 로드되지 않다가, AI가 필요하다고 판단할 때만 컨텍스트에 추가된다.Q: Tool Search Tool은 지금 바로 사용할 수 있나요?
A: Anthropic API를 직접 호출하는 경우에만 베타로 사용 가능하다.
betas=["advanced-tool-use-2025-11-20"] 헤더를 추가하면 된다. Claude Code CLI(터미널에서 claude 명령어)에서는 아직 지원되지 않는다.Q: mcp-cli가 토큰 최적화 치트키인가요?
A: 아니다.
mcp-cli는 MCP 서버 관리 및 디버깅을 위한 CLI 도구로, 토큰을 직접 절감하는 기능이 없다. 다만, 연결된 MCP 서버와 도구 현황을 파악하여 불필요한 서버를 식별하고 비활성화하는 데 활용할 수 있다. 이런 점에서 간접적인 최적화 지원 도구라고 볼 수 있다.Q: 현재 Claude Code CLI에서 토큰을 줄이는 가장 빠른 방법은?
A:
/mcp disable [server-name] 명령어로 불필요한 MCP 서버를 비활성화하거나, --strict-mcp-config 옵션으로 필요한 MCP만 로드하는 것이다.Q: mcp-cli와 claude mcp의 차이점은 무엇인가요?
A:
mcp-cli는 도구 조회/검색/호출을 위한 CLI 명령어이고, claude mcp는 서버 설정 관리(추가/제거/목록)를 위한 서브커맨드다. mcp-cli tools로 도구 상세 목록을 확인하고, claude mcp list로 서버별 도구 수와 연결 상태를 한눈에 파악할 수 있다.Q: 도구가 많으면 왜 정확도가 떨어지나요?
A: Anthropic에 따르면, 도구가 너무 많으면 AI가 적절한 도구를 선택하는 데 혼란을 겪을 수 있다. Tool Search Tool은 필요한 도구만 로드하여 이 문제를 해결한다.
핵심 요약: 즉시 로드 → 지연 로드로 전환!
- 문제: MCP 도구가 많으면 컨텍스트의 50%~72%까지 차지 (Issue #12836: 73.9k 토큰 사례)
- Anthropic 솔루션: Tool Search Tool(85%) + Programmatic Tool Use(+37%) = 최대 90%+ 토큰 절감
- 정확도 향상: Tool Use Examples로 복잡한 도구 사용 정확도 72%→90%
- Claude Code CLI 현황: defer_loading 아직 미지원 (Feature Request 상태) - Anthropic "Stay tuned" 응답
- 커뮤니티 대안: MCP Proxy, MCP Gateway, Docker MCP Toolkit (참고용)
- 현재 가능한 최적화: MCP 비활성화, --allowedTools 옵션, 구성 파일 분리 (v2.0.69+)
- mcp-cli 직접 호출: 단순 조회는
mcp-cli call로 세션 없이 실행 → 토큰 100% 절약 (v2.0.69+)
참고 자료
공식 자료
- Anthropic Engineering - Advanced Tool Use - 공식 Tool Search Tool 발표
- Claude Code CLI Usage Documentation - 공식 CLI 문서
GitHub Issues
- Issue #7336 - Lazy Loading 기능 요청
- Issue #12836 - Tool Search 베타 지원 요청
커뮤니티 자료
- Scott Spence - Optimising MCP Server Context Usage - 도구 통합 최적화 사례
- MCP Proxy - 여러 MCP 서버 통합 프록시
- MCP Gateway - MCP 서버 중앙 관리 게이트웨이
- Docker MCP Toolkit - Docker 기반 MCP 통합 솔루션
300x250
'AI > MCP' 카테고리의 다른 글
| Anthropic MCP 프로토콜 1년의 진화 - OpenAI 채택부터 Linux Foundation 이관까지 (2) | 2025.12.15 |
|---|---|
| 개발자를 위한 MCP 추천(8) - CODEX MCP 설치 및 사용방법 (1) | 2025.11.14 |
| 개발자를 위한 MCP 추천(7) - Figma MCP 설치 방법 (5) | 2025.10.21 |
| 개발자를 위한 MCP 추천(6) - Magic MCP 설치 및 사용방법 (6) | 2025.10.15 |
| 개발자를 위한 MCP 추천(5) - Shrimp Task Manager MCP 설치 및 사용방법(claude code 사용 예시) (4) | 2025.08.20 |
Contents
소중한 공감 감사합니다