Claude's Web Tools Got a Domain Allowlist. Here's What It Doesn't Cover

What the domain allowlist actually does

Claude's web_search and web_fetch server tools accept an allowed_domains or blocked_domains setting that limits which hosts the tool can reach on a single Messages API request. The web search tool's own reference states you provide allowed_domains or blocked_domains, not both, and that a request including both returns a 400 error. The web fetch tool carries the equivalent setting, and both tools share the same validation logic under the umbrella of Anthropic's server tools documentation.

Claude Managed Agents has a parallel version of the same control, configured once per agent rather than once per request. The Managed Agents documentation describes two list types on the toolset's web_search and web_fetch entries: an allowed_domains list, where the tool can reach only the listed hosts, and a blocked_domains list, where the tool can never reach them, with each tool carrying its own independent list so a single agent can have different rules for search versus fetch.

Sources: Web search tool - Claude Platform Docs, Server tools - Claude Platform Docs, Restrict web search and web fetch domains - Claude Platform Docs.

How the matching rules work

The matching behavior differs slightly by tool. For web search, a specific subdomain in the list restricts results to that subdomain only, and subpaths are supported, so an entry like example.com/blog matches example.com/blog/post-1. Web fetch matches on the domain alone: an entry that includes a path never matches a web fetch URL, and wildcards are not allowed in the domain itself, a constraint set out in the web fetch tool's own reference. A listed bare domain, however, covers all of its own subdomains automatically.

Managed Agents layers four extra constraints on top of the same field names used by the Messages API server tools: each list is capped at 64 domains, web_fetch entries cannot include a path at all, domains must be ASCII rather than Unicode, and the per-request settings max_uses, citations, and cache_control are not available on the agent toolset. These differences matter if you're porting a domain list written for a direct Messages API call into an agent definition; copying it verbatim can fail validation if it includes a path on a web_fetch entry or a Unicode domain.

Sources: Server tools - Claude Platform Docs, Restrict web search and web fetch domains - Claude Platform Docs, Web fetch tool - Claude Platform Docs.

What the allowlist does not restrict

The domain list is a tool-level setting, not a network-level firewall, and Anthropic's own security guidance for Managed Agents deployments is explicit about the boundary: the web tools run on Anthropic's servers, so your firewall does not limit them, and you limit them only with their domain lists. That statement cuts both ways. It also means the domain list on web_search and web_fetch has no bearing on anything else the agent can do over the network.

If the same agent has a bash tool or runs arbitrary code, that access is governed by the sandbox's own networking configuration, not by allowed_domains or blocked_domains on the web tools. The cloud environment documentation describes a separate allowed_hosts setting for limited networking, and warns that with unrestricted networking, code in the sandbox can send requests to any host on the internet except a general safety blocklist, which is explicitly described as not an allowlist. It does not limit which other sites the agent reaches, or what the agent does on them. A bot with both web_fetch and a shell tool is really running two separate access boundaries that happen to live in the same agent definition, and locking down one does nothing to the other.

The secure-deployment guidance adds a related point about credentials: even when an API key sits in a vault, code running in the sandbox can use it to call the Claude API directly, doing anything that key allows, and the agent's own tool settings, approvals, and budget do not apply to those calls. A domain-restricted web_fetch tool does not stop a bash tool from fetching a token and using it outside the agent's configured limits.

Sources: Secure your Managed Agents deployment - Claude Platform Docs, Cloud environment setup - Claude Platform Docs.

A worked example: a research bot that should only read two sites

Say a small team builds a research agent on Claude Managed Agents that should only read docs.anthropic.com and arxiv.org, never general web content. The agent's toolset config sets web_search's allowed_domains to those two hosts, with web_fetch configured separately, matching the shape shown in Anthropic's own example: a YAML agent definition listing type: agent_toolset_20260401 with a web_search config entry carrying allowed_domains: [docs.anthropic.com, arxiv.org] alongside a user_location setting, and a web_fetch config entry with its own domain and content-size limits.

The failure path is worth planning for before it happens in production. Managed Agents checks the configuration again when a session first initializes the tool, not only when you first set it. If a domain list that validated earlier is no longer valid at that point, for instance because a cloud environment's allowed_hosts changed, the session emits a session.error event and returns to idle without retrying. The documented fix is to update the session's tools, update the agent definition too so new sessions inherit the correction, and then send a new message to continue. A bot that treats session.error as a generic failure and retries blindly will loop without ever fixing the underlying mismatch between the tool's domain list and the environment's host list.

If this same research agent also had a bash tool with unrestricted networking, the domain list on web_search and web_fetch would still only govern those two tools. A compromised or poorly prompted agent could still reach arbitrary hosts through bash, independent of how tightly docs.anthropic.com and arxiv.org were locked down on the web tools.

Sources: Restrict web search and web fetch domains - Claude Platform Docs.

The decision to make before you turn this on

Before relying on allowed_domains or blocked_domains as your only access boundary, check three things.

First, confirm where the setting actually applies. Organization-level web search and web fetch settings configured on the Capabilities page of the Claude Console apply to the Messages API, and separately, your organization's web search and web fetch settings also apply to a Managed Agents session, but the per-tool allowed_domains and blocked_domains on the agent's own toolset are what you control directly at the agent level. Setting an org-wide restriction in the Console does not substitute for setting the per-tool list on the agent definition.

Second, inventory every tool the agent has, not just web_search and web_fetch. If the agent also has a bash tool, a code execution tool, or MCP connectors, those need their own boundary: the cloud environment's networking type and allowed_hosts for sandboxed code, and allow_mcp_servers plus a trusted host list for MCP traffic. A tight web_fetch allowlist on an agent that also has unrestricted bash networking is a false sense of security.

Third, pick allowlist over blocklist by default. An allowed_domains list can only shrink what the tool reaches; a blocked_domains list leaves everything else open, including domains you haven't thought of yet. For a bot that only ever needs a handful of known sources, write down that short list and use allowed_domains, then revisit it the same way you'd revisit any other credential scope.

Sources: Restrict web search and web fetch domains - Claude Platform Docs, Cloud environment setup - Claude Platform Docs.