Claude Code가 느려졌다면? MCP 도구 관리가 답이다

Claude Code를 쓰다 보면 어느 순간 응답이 느려지고, 엉뚱한 도구를 선택하는 경험을 하게 됩니다. MCP 서버를 여러 개 연결해서 "만능 에이전트"를 만들었는데, 오히려 성능이 떨어진 것 같은 느낌. 이 글에서는 왜 이런 일이 발생하는지, 그리고 어떻게 최적화할 수 있는지 정리합니다.

---

TL;DR

• MCP 도구는 매 요청마다 컨텍스트 윈도우를 차지합니다
• 도구가 많으면 느려지는 게 아니라 정확도도 떨어집니다
• 프로젝트별로 필요한 MCP만 활성화하세요
• /doctor와 /context 명령으로 현재 상태를 점검하세요

---

문제: "도구가 많으면 좋은 거 아닌가요?"

GitHub MCP, Notion MCP, PostgreSQL MCP, Slack MCP... 연결할 수 있는 건 다 연결해두면 편할 것 같죠? 실제로는 정반대입니다.

한 개발자의 사례를 보면, MCP 도구들이 대화 시작 전에 이미 **82,000 토큰(전체의 41%)**을 차지했습니다. 200K 토큰 윈도우 중 143K(72%)가 이미 사용되어 **자유 공간이 5.8%**밖에 남지 않았어요. 코드 한 줄 보여주기도 전에 말이죠.

더 극단적인 사례도 있습니다. MCP_DOCKER 하나만으로 135개 도구, 125,964 토큰을 소비한 경우도 보고되었습니다.

---

왜 이런 일이 발생하나?

1. 컨텍스트 윈도우의 구조

Claude Code가 작업할 때 컨텍스트 윈도우는 대략 이렇게 나뉩니다:

┌─────────────────────────────────────────────────────┐
│  Claude의 컨텍스트 윈도우 (200K 토큰)                │
├─────────────────────────────────────────────────────┤
│  시스템 프롬프트: ~3K                                │
│  시스템 도구: ~12K                                   │
│  MCP 도구 정의: ???  ← 여기가 변수                   │
│  예약 공간: ~45K (autocompact + 출력)                │
│  실제 대화/코드: 남은 공간                           │
└─────────────────────────────────────────────────────┘

MCP 도구는 매 요청마다 전체 정의(이름, 설명, 파라미터 스키마)가 컨텍스트에 포함됩니다. 도구 하나당 수백~수천 토큰이 "고정 비용"으로 빠져나갑니다.

2. 도구 선택의 인지 부하

Claude가 응답할 때 내부적으로 이런 과정을 거칩니다:

1. 사용자 요청 분석
2. 사용 가능한 모든 도구 검토 ← 여기서 도구가 많으면 복잡해짐
3. 적절한 도구 선택
4. 파라미터 결정

비슷한 기능의 도구가 여러 개 있으면 "파일 읽기를 read_file로 할까, view로 할까, cat으로 할까?" 같은 판단이 필요해지고, 잘못된 선택 확률도 올라갑니다.

3. 실제 정확도 하락 데이터

Anthropic 내부 테스트 결과, 대규모 도구 라이브러리에서 도구 수를 최적화하면:

모델 최적화 전 최적화 후

Opus 4	49%	74%
Opus 4.5	79.5%	88.1%

도구가 많으면 Claude가 잘못된 도구를 선택할 확률이 거의 2배 높아집니다.

---

해결책 1: 수동 최적화

기본 원칙

✅ MCP 서버: 20~30개 설정해두되, 동시 활성화는 10개 미만
✅ 전체 도구 수: 80개 이하 유지
✅ 프로젝트별로 필요한 MCP만 켜기

현재 상태 점검하기

# 컨텍스트 사용량 확인
/context

# MCP 서버별 토큰 사용량 상세 확인
/doctor

/doctor 출력 예시:

Context Usage Warnings
└ ⚠️ Large MCP tools context (~81,986 tokens > 25,000)
└ MCP servers:
    └ mcp-omnisearch: 20 tools (~14,114 tokens)
    └ playwright: 21 tools (~13,647 tokens)
    └ mcp-sqlite-tools: 19 tools (~13,349 tokens)
    ...

MCP 토글 도구 활용

프로젝트마다 필요한 MCP를 켜고 끄는 게 번거롭다면, McPick 같은 CLI 도구를 활용할 수 있습니다:

npx mcpick

# 대화형으로 MCP 서버 켜기/끄기
? Select MCP servers to enable/disable:
◉ mcp-omnisearch (enabled)
◯ playwright (disabled)
◉ sequential-thinking (enabled)

---

해결책 2: Tool Search 활용 (2026년 1월~)

Anthropic이 이 문제를 인식하고 MCP Tool Search 기능을 출시했습니다.

Tool Search란?

모든 도구 정의를 미리 로드하는 대신, Claude가 필요할 때만 도구를 동적으로 검색하고 로드합니다.

효과

지표 기존 방식 Tool Search

토큰 사용량 (50+ 도구)	~77K	~8.7K
절감률	-	85%
자유 컨텍스트	5.8%	44%+

작동 방식

1. Claude Code가 MCP 도구 정의가 전체 컨텍스트의 ~10%를 넘는지 확인
2. 임계값을 넘으면 도구를 defer_loading: true로 마킹
3. 실제 필요할 때만 해당 도구 정의를 로드

설정 방법

# 환경 변수로 제어
ENABLE_TOOL_SEARCH=true  # 강제 활성화
ENABLE_TOOL_SEARCH=false # 비활성화
# 미설정 시 auto 모드 (임계값 기반 자동 활성화)

주의사항

• Sonnet 4 이상, Opus 4 이상에서만 지원
• Haiku 모델은 Tool Search 미지원
• 자주 쓰는 도구는 defer_loading: false로 미리 로드해두는 게 효율적

---

프로젝트별 MCP 구성 예시

MCP 설정 파일 위치

Claude Code의 MCP 설정은 **scope(범위)**에 따라 다른 파일에 저장됩니다:

Scope 파일 위치 용도

User (전역)	~/.claude.json	모든 프로젝트에서 사용하는 개인 설정
Project (프로젝트 공유)	프로젝트루트/.mcp.json	팀과 공유할 프로젝트별 설정 (Git에 커밋)
Local (프로젝트 개인)	프로젝트루트/.claude/settings.local.json	개인용 프로젝트 설정 (Git 제외)

💡 팁: CLI로 MCP를 추가할 때 --scope 플래그로 저장 위치를 지정할 수 있습니다.

# 전역 설정에 추가
claude mcp add github --scope user  -- npx -y @modelcontextprotocol/server-github

# 프로젝트 설정에 추가 (팀 공유용)
claude mcp add github -s project -- npx -y @modelcontextprotocol/server-github

웹 개발 프로젝트

파일: 프로젝트루트/.mcp.json

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PAT}"
      }
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-playwright"]
    }
  }
}

사용하지 않는 MCP는 아예 파일에서 제외하거나, McPick 같은 도구로 토글하세요.

데이터 분석 프로젝트

파일: 프로젝트루트/.mcp.json

{
  "mcpServers": {
    "postgresql": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "sqlite": {
      "command": "npx",
      "args": ["-y", "mcp-sqlite-tools"]
    }
  }
}

문서 작업

파일: ~/.claude.json (전역 설정으로 관리하면 편리)

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "notion-mcp-server"],
      "env": {
        "NOTION_API_KEY": "${NOTION_API_KEY}"
      }
    },
    "gdrive": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-gdrive"]
    }
  }
}

설정 확인 명령어

# 현재 연결된 MCP 서버 상태 확인
/mcp

# 출력 예시:
# MCP Server Status
# • github: connected
# • postgresql: connected
# • notion: disconnected

---

체크리스트: Claude Code 최적화

• [ ] /doctor로 MCP 토큰 사용량 확인
• [ ] 25,000 토큰 넘으면 경고 — 불필요한 MCP 비활성화
• [ ] 프로젝트별 .claude.json 설정 분리
• [ ] Tool Search 지원 모델 사용 시 auto 모드 활용
• [ ] 자주 쓰는 도구는 항상 로드, 가끔 쓰는 도구는 검색 대상으로

---

마무리

"도구가 많을수록 좋다"는 직관과 달리, AI 에이전트에서는 적절한 도구 수 관리가 성능의 핵심입니다. 컨텍스트 윈도우는 유한한 자원이고, 도구 정의도 그 자원을 소비합니다.

Tool Search 기능이 나오면서 제약이 많이 완화되었지만, 여전히 프로젝트별로 필요한 MCP만 활성화하는 습관은 유효합니다. 더 빠른 응답, 더 정확한 도구 선택, 더 넓은 작업 공간을 원한다면 지금 바로 /doctor를 실행해보세요.

---

참고 자료

• Anthropic Engineering: Claude Code Best Practices
• Anthropic Engineering: Advanced Tool Use
• Claude Code Docs: MCP