Claude API web fetch 도메인 제한: 조직 정책과 요청별 허용 목록 설정

Claude API가 지정한 사이트만 읽도록 하려면 Console의 조직 정책과 요청의 allowed_domains를 함께 점검해야 합니다. 조직 관리자는 web fetch 사용 여부와 도메인 정책을 정하고, 개발자는 Messages API 요청의 도구 객체에 작업별 허용 목록을 넣습니다.

이 글에서 사용하는 주요 용어 정의

용어의미

web fetch	지정한 웹페이지의 내용을 가져오는 서버 도구
조직 정책	Claude Console에서 관리자가 설정하는 web fetch 사용·도메인 제한
allowed_domains	도구가 접근할 수 있는 호스트를 지정하는 허용 목록
blocked_domains	접근을 막을 호스트를 지정하는 차단 목록

1. Console에서 조직 정책 설정하기

Anthropic의 2026년 10월 20일 릴리스 노트에 따르면, 조직 관리자는 Claude Console의 Capabilities에서 web fetch를 끄거나 허용·차단 도메인을 설정할 수 있습니다.

먼저 관리자가 web fetch 활성 여부를 확인합니다. 활성화한 상태에서 조직의 도메인 정책을 정하고, API에서 읽을 호스트가 그 정책에 허용되도록 맞춥니다. 예를 들어 Claude API 문서를 읽는 작업이라면 platform.claude.com이 조직 정책에 걸리지 않아야 합니다.

조직에서 web fetch를 꺼 두면 해당 도구를 포함한 Messages API 요청은 HTTP 400으로 실패합니다. 이때는 요청의 허용 목록을 고쳐도 해결되지 않으므로 조직 설정부터 점검해야 합니다.

2. 요청의 tools에 허용 목록 넣기

아래는 공식 문서 기반의 미실행 JSON 예제입니다. 기존 Messages API 요청에 반영할 tools와 messages 부분만 제시했습니다. 기존 요청의 나머지 필드는 유지합니다.

{
  "tools": [
    {
      "type": "web_fetch_20250910",
      "name": "web_fetch",
      "allowed_domains": ["platform.claude.com"]
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool 페이지를 읽고 도메인 제한 설정을 요약해 주세요."
    }
  ]
}

allowed_domains는 요청 최상위가 아니라 tools 안의 web fetch 객체에 둡니다. 예제의 web_fetch_20250910은 기본 fetch 버전입니다. 읽을 URL도 사용자 메시지에 직접 넣어 선행 문맥에 존재하도록 구성했습니다.

특정 호스트를 제외하는 방식이 필요하면 allowed_domains 대신 blocked_domains를 사용합니다. 두 목록을 같은 도구에 동시에 지정하지 않습니다. 호출 횟수를 조절하는 max_uses는 도메인 제한과 별개입니다.

3. 도메인은 URL이 아닌 호스트로 입력하기

Anthropic의 Server tools 문서는 도메인 필터의 입력 범위를 다음과 같이 설명합니다.

입력web fetch에서의 의미·주의점

example.com	해당 호스트와 하위 도메인을 포함
docs.example.com	상위 example.com이나 형제 api.example.com은 허용하지 않음
https://example.com	스킴을 빼고 example.com으로 입력
*.example.com	호스트의 *는 허용되지 않음
example.com/docs	경로가 들어간 항목은 web fetch URL과 매칭되지 않음

따라서 문서 사이트만 읽게 하려면 필요한 호스트를 좁게 지정하세요. web search의 경로 필터 예제를 web fetch에 그대로 적용하면 안 됩니다.

4. HTTP 상태와 도구 오류를 따로 확인하기

web fetch는 HTTP 200이어도 도구 실행에 실패할 수 있습니다. Web fetch tool 문서에 따르면 응답 안의 web_fetch_tool_result_error도 읽어야 합니다.

응답·오류점검할 항목

HTTP 400	조직의 web fetch 비활성화 여부, 도메인 필드 등 요청 형식
url_not_allowed	조직·요청 도메인 필터와 Anthropic 측 접근 제한
url_not_in_prior_context	URL이 앞선 문맥에 있는지, 허용된 URL 출처인지

url_not_allowed만 보고 조직 관리자가 차단했다고 단정할 수는 없습니다. Anthropic 측 제한도 원인이 될 수 있으므로 조직 설정과 요청 목록을 확인한 뒤 다른 접근 제한을 구분해야 합니다.

실무에서는 조직 정책과 요청 목록 양쪽에서 대상 호스트를 허용하도록 구성하세요. 요청별 허용 목록을 조직 제한을 해제하는 수단으로 취급해서는 안 됩니다.

이 예제는 Messages API용입니다. Managed Agents는 에이전트 toolset의 configs에서 설정하므로 같은 JSON 위치를 사용하지 않습니다.

설정을 반영한 뒤에는 허용한 호스트와 목록 밖 호스트를 각각 읽도록 요청하고, HTTP 상태와 도구 결과를 함께 비교하세요. 도메인 허용만으로 페이지를 반드시 가져올 수 있는 것은 아닙니다.

참고 링크

• Anthropic — Web fetch tool
• Anthropic — Server tools: Domain filtering