웹 도구

웹 도구 개요

Claude Code는 인터넷에 직접 접근할 수 있는 두 가지 도구를 제공합니다. WebFetch는 특정 URL의 내용을 가져오고, WebSearch는 검색 쿼리로 관련 페이지를 찾습니다.

두 도구 모두 기본 모드에서 사용자 승인이 필요 합니다. 외부 네트워크 접근은 데이터 유출 위험이 있으므로 자동 승인하지 않습니다.

WebFetch 도구

지정한 URL의 웹 페이지를 가져와 모델이 처리할 수 있는 형태로 변환합니다.

처리 파이프라인

URL 입력
  ↓
HTTP → HTTPS 자동 업그레이드
  ↓
리다이렉트 처리 (최대 5회)
  ↓
HTML 다운로드
  ↓
HTML → 마크다운 변환 (불필요한 태그 제거)
  ↓
보조 모델(서브에이전트)로 내용 처리
  ↓
관련 정보 추출 후 반환

HTML → 마크다운 변환

원시 HTML은 모델이 처리하기에 적합하지 않습니다. JavaScript 코드, CSS, 광고, 네비게이션 등 실제 내용과 무관한 데이터가 많기 때문입니다. WebFetch는 이를 마크다운으로 변환 하여 핵심 내용만 추출합니다.

<!-- 원본 HTML (단순화) -->
<nav>...</nav>
<article>
  <h1>React Hooks 가이드</h1>
  <p>useState는 함수형 컴포넌트에서...</p>
  <pre><code>const [count, setCount] = useState(0)</code></pre>
</article>
<footer>...</footer>

<!-- 변환된 마크다운 -->
# React Hooks 가이드

useState는 함수형 컴포넌트에서...

```javascript
const [count, setCount] = useState(0)

### 캐싱

동일한 URL은 **15분간 캐싱** 됩니다. 같은 세션에서 동일 URL을 여러 번 요청해도 네트워크 요청은 한 번만 발생합니다.

```typescript
// WebFetch 파라미터
{
  url: "https://docs.anthropic.com/claude-code",
  prompt: "이 페이지에서 설치 방법만 추출해줘"  // 선택적 처리 지시
}

prompt 파라미터를 지정하면 보조 모델이 해당 지시에 따라 내용을 처리합니다. 지정하지 않으면 전체 내용을 반환합니다.

HTTP → HTTPS 자동 업그레이드

보안을 위해 http:// URL은 자동으로 https:// 로 변환됩니다.

http://example.com/docs → https://example.com/docs

HTTPS를 지원하지 않는 서버라면 연결 오류가 발생합니다.

WebSearch 도구

검색 쿼리를 입력받아 관련 웹 페이지 목록을 반환합니다.

반환 형식

검색 결과는 마크다운 링크 목록 형태로 반환됩니다.

검색 결과: "claude code mcp setup"

1. [MCP 서버 설정 가이드](https://docs.anthropic.com/mcp-setup)
   Claude Code에서 MCP 서버를 연결하는 방법을 설명합니다...

2. [Model Context Protocol 공식 문서](https://modelcontextprotocol.io)
   MCP 프로토콜의 공식 사양과 구현 가이드...

3. [Claude Code MCP 튜토리얼](https://example.com/tutorial)
   단계별 MCP 서버 구축 예제...

각 결과에는 제목, URL, 스니펫(요약) 이 포함됩니다.

자동 출처 표시

WebSearch를 사용한 응답에는 자동으로 출처가 표시됩니다. 모델이 검색 결과를 바탕으로 답변할 때 어떤 페이지를 참조했는지 추적할 수 있습니다.

<!-- 모델 응답 예시 -->
Claude Code에서 MCP 서버를 설정하려면 `.claude/settings.json`에
mcpServers 키를 추가해야 합니다.

출처: [MCP 서버 설정 가이드](https://docs.anthropic.com/mcp-setup)

지역 제한

WebSearch는 현재 미국(US) 전용 으로 제공됩니다. 다른 지역에서는 isEnabled() 가 false 를 반환하여 도구가 비활성화됩니다.

// WebSearch isEnabled 구현 (단순화)
isEnabled(): boolean {
  return process.env.CLAUDE_CODE_REGION === 'US'
    || process.env.CLAUDE_CODE_WEBSEARCH_ENABLED === '1'
}

두 도구 비교

항목	WebFetch	WebSearch
입력	특정 URL	검색 쿼리 문자열
출력	페이지 전체 내용 (마크다운)	결과 목록 (제목/URL/스니펫)
캐싱	15분	캐싱 없음
권한	ask (승인 필요)	ask (승인 필요)
지역 제한	없음	미국 전용
용도	특정 문서 내용 확인	모르는 정보 검색

실용적인 사용 패턴

공식 문서 확인

// 라이브러리 최신 API 확인
WebFetch: {
  url: "https://react.dev/reference/react/useState",
  prompt: "useState의 타입 시그니처와 반환값을 정리해줘"
}

오류 메시지 검색

// 모르는 오류 원인 파악
WebSearch: {
  query: "TypeError: Cannot read properties of undefined reading 'map' React"
}
// → 관련 Stack Overflow, GitHub Issues 결과 반환

패키지 최신 버전 확인

// npm 패키지 최신 버전 확인
WebFetch: {
  url: "https://registry.npmjs.org/react/latest",
  prompt: "최신 버전 번호만 알려줘"
}

권한 설정

웹 도구 접근을 자동화하려면 설정 파일에서 명시적으로 허용합니다.

{
  "permissions": {
    "allow": [
      "WebFetch(docs.anthropic.com:*)",  // Anthropic 문서만 자동 허용
      "WebSearch(*)"                      // 모든 검색 자동 허용
    ],
    "deny": [
      "WebFetch(*.internal.company.com:*)"  // 내부 도메인 차단
    ]
  }
}