2.5내장 툴

서버 툴(server tools) 은 Anthropic 인프라에서 실행되어 tool_result 왕복이 필요 없는 툴입니다. 대표적으로 두 가지를 알아야 합니다.

웹 검색(web search): 모델이 최신 정보를 검색해 답변에 인용과 함께 반영합니다. max_uses로 검색 횟수를 제한하고, allowed_domains/blocked_domains로 출처를 통제할 수 있습니다.

{
  "type": "web_search_20250305",
  "name": "web_search",
  "max_uses": 3,
  "allowed_domains": ["docs.anthropic.com", "github.com"]
}

코드 실행(code execution): 샌드박스 컨테이너에서 Python 코드를 실행합니다. 데이터 분석, 계산, 파일 처리에 쓰이며, 모델이 코드를 작성→실행→결과 확인→수정하는 반복을 API 안에서 수행합니다.

서버 툴의 공통 특징은 다음과 같습니다.

• 타입 문자열에 버전이 포함됩니다 (web_search_20250305). 버전 고정으로 동작 변경에 대비하는 것입니다
• 실행이 Anthropic 쪽에서 일어나므로 여러분의 코드에 실행 로직이 없습니다
• 사용량 기반 추가 요금이 부과될 수 있습니다 (예: 웹 검색은 검색 건당 과금)

시험에서는 "최신 문서를 참조해 답해야 하는 기능"을 구현하는 문제에서 웹 검색 서버 툴을 고르는 것, 그리고 서버 툴과 클라이언트 툴의 실행 주체 구분이 핵심입니다.

Anthropic은 스키마가 표준화된 공식 클라이언트 툴 타입도 제공합니다. 정의(스키마)는 Anthropic이 관리하지만 실행은 여러분의 환경에서 합니다. 모델이 해당 툴 사용법에 대해 특별히 훈련되어 있어, 같은 기능을 커스텀 스키마로 만드는 것보다 성능이 좋습니다.

• bash 툴 (bash_20250124 등): 셸 명령 실행. 여러분이 샌드박스를 준비하고 명령을 실행해 결과를 돌려줍니다
• 텍스트 에디터 툴 (text_editor_20250728 등): 파일 보기·생성·문자열 치환 편집. str_replace 기반의 정밀 편집 명령을 모델이 능숙하게 사용합니다
• 컴퓨터 사용 툴(computer use) (computer_20250124 등): 스크린샷을 보고 마우스·키보드를 조작하는 GUI 자동화. 베타 헤더가 필요합니다

{
  "tools": [
    { "type": "bash_20250124", "name": "bash" },
    { "type": "text_editor_20250728", "name": "str_replace_based_edit_tool" }
  ]
}

핵심 주의점은 실행 책임입니다. bash 툴을 켠다는 것은 모델이 생성한 임의 명령을 여러분 환경에서 실행한다는 뜻이므로, 컨테이너 격리·권한 제한·위험 명령 필터링은 전적으로 구현자의 몫입니다. "공식 툴이니 안전하다"는 전제는 오답 포인트입니다.

이 계열 툴을 쓰는 판단 기준: 파일 편집·셸 실행·GUI 조작처럼 모델이 훈련된 표준 작업이라면 커스텀 스키마를 발명하지 말고 공식 타입을 쓰는 것이 낫습니다.

Claude Code는 코딩 작업에 필요한 툴이 이미 갖춰진 환경입니다. 주요 내장 툴의 역할 구분을 알아야 합니다.

툴	역할
Read / Write / Edit	파일 읽기, 새 파일 작성, 부분 수정
Bash	셸 명령 실행 (빌드, 테스트, git 등)
Grep / Glob	내용 검색, 파일명 패턴 검색
Task(서브에이전트)	별도 컨텍스트에서 탐색·작업 위임
WebFetch / WebSearch	웹 문서 조회·검색

이 목록이 시험에서 중요한 이유는 중복 구현 판별 때문입니다. 다음은 모두 잘못된 설계입니다.

• 파일을 읽는 MCP 서버를 만든다 → Read/Grep이 이미 있음
• git 커밋 MCP 툴을 만든다 → Bash로 git CLI를 쓰면 됨
• GitHub PR 조회 서버를 급조한다 → gh CLI가 설치돼 있다면 Bash로 충분하고, 더 풍부한 통합이 필요할 때 공식 GitHub MCP 서버를 연결

즉 Claude Code에서 새 능력이 필요할 때의 점검 순서는 내장 툴 → 기존 CLI(Bash 경유) → 기존 MCP 서버 → 직접 개발 입니다. 이 순서를 뒤집은 선택지(바로 직접 개발)가 전형적인 오답입니다.

또한 내장 툴은 권한 시스템과 통합되어 있습니다. 파일 쓰기·Bash 실행은 승인 대상이며, settings.json의 permissions로 팀 정책(허용·차단 목록)을 설정합니다. 커스텀 MCP 툴에는 이런 정교한 기본 권한 UX가 자동으로 따라오지 않는다는 차이도 알아 두세요.

도메인 2 전체를 관통하는 마지막 질문은 "이 툴을 정말 만들어야 하는가"입니다. 결정 프레임을 정리합니다.

필요한 능력이 생겼다
│
├─ 1. Anthropic 서버 툴로 되는가? (웹 검색, 코드 실행)
│     → 예: 그대로 사용. 실행 인프라 불필요
├─ 2. 공식 클라이언트 툴 타입이 있는가? (bash, 에디터, 컴퓨터 사용)
│     → 예: 공식 타입 사용. 커스텀 스키마보다 성능 우수
├─ 3. (Claude Code) 내장 툴 + 기존 CLI로 되는가?
│     → 예: 새로 만들지 않는다
├─ 4. 기존 MCP 서버가 있는가? (공식/커뮤니티)
│     → 예: 신뢰성 검증 후 연결
└─ 5. 여기까지 아니면 → 직접 개발
      └─ 단일 앱 전용 → API에 직접 정의
      └─ 공유/재사용 → 자체 MCP 서버

이 순서의 근거는 세 가지입니다. 비용: 만들지 않는 툴이 가장 싼 툴입니다. 성능: 공식 툴은 모델이 훈련된 인터페이스라 커스텀 재발명보다 정확도가 높습니다. 유지보수: 직접 만든 툴은 스키마 개선(2.1), 오류 설계(2.2), 보안 점검(2.4)까지 전부 여러분의 지속적 책임이 됩니다.

단, 기성품 우선 원칙에도 예외가 있습니다. 서드파티 MCP 서버는 공급망 신뢰 검증이 안 되면 직접 만드는 편이 안전할 수 있고, 도메인 특화 로직(사내 규칙이 얽힌 복합 작업)은 범용 툴 조합보다 전용 툴 하나가 정확도와 토큰 효율 모두 나을 수 있습니다. '무조건 기성품'이 아니라 검토 순서라는 점을 기억하세요.