Claude Managed Agents Domain Restrictions: A Fix Guide

Claude Managed Agents in limited networking environments enforce domain limits through environment-level allowed_hosts and tool-level allowed_domains or blocked_domains arrays. If a host is not in allowed_hosts, the agent receives a url_not_allowed error for web_fetch and web_search silently omits those results. Setting this up requires aligning your environment networking policies with your tool configurations.

The Claude Platform release notes detail two layers of control. You configure network egress for the sandbox using allowed_hosts, and you restrict specific tools using allowed_domains or blocked_domains on the tool's entry in the agent_toolset_20260401 configs array. If the tool-level list includes a host missing from the environment-level list, session creation fails with a 400 error. Getting this right prevents data exfiltration and keeps your agents from reaching unintended domains.

How environment allowed_hosts limits web tools#

As of October 7, 2026, a cloud environment with limited networking applies its allowed_hosts list to the web_search and web_fetch tools. This means your environment network policy is the single source of truth for outbound web traffic from the agent. If a host is not listed in allowed_hosts, the tools cannot reach it.

When allowed_hosts does not match a requested host, web_fetch returns a url_not_allowed error result to the agent. The web_search tool omits results from such hosts entirely. If allowed_hosts lists no hosts, neither tool returns a page or a search result. To let the tools reach a host, you must add it to allowed_hosts, which also opens it to the sandbox.

The allow_package_managers and allow_mcp_servers settings do not add hosts for these web tools. If you want your agent to fetch a package registry URL or an MCP server endpoint over HTTP using web_fetch, you must explicitly add those hosts to allowed_hosts. Unrestricted networking and self-hosted environments do not limit these tools, so these restrictions only apply when you explicitly configure limited networking.

Configure allowed_domains and blocked_domains on tools#

For finer control over what the web_search and web_fetch tools can access, you can set allowed_domains or blocked_domains directly on the tool's configuration. The Claude Platform release notes from August 19, 2026 state that you set these on the tool's entry in the agent_toolset_20260401 configs array.

Each config entry is identified by its name and typed by an optional type. Requests that pass only name, enabled, and permission_policy continue to work, but adding allowed_domains or blocked_domains lets you scope the tool's behavior. The web_fetch tool also accepts max_content_tokens and web_search accepts user_location in this same config object.

Here is an example of how you might structure this configuration within an agent definition. This JSON excerpt shows the configs array for a web_fetch tool, limiting it to a specific domain.

{
  "tools": [
    {
      "name": "web_fetch",
      "type": "web_fetch",
      "enabled": true,
      "configs": [
        {
          "name": "web_fetch",
          "allowed_domains": ["docs.example.com"],
          "max_content_tokens": 1000
        }
      ]
    }
  ]
}

If you want to block a specific domain but allow everything else permitted by allowed_hosts, use blocked_domains instead. This is useful when you want the agent to have general web access but prevent it from reaching a known internal or problematic host.

The web_fetch prior context rule#

Domain restrictions are not the only limit on web_fetch. As of October 7, 2026, the web_fetch tool fetches only URLs that have already appeared in the session. This includes URLs in the text of a user message, a web_search result, or a page that web_fetch returned earlier. This reduces the risk of data exfiltration.

A URL that appears only in Claude's own output, the agent's system prompt, an attached document, or the output of a tool such as bash, read, or an MCP tool does not count. A web_fetch call for such a URL returns a url_not_in_prior_context error result to the agent.

To let the agent fetch a URL that has not appeared in prior context, send that URL in the text of a user.message event. This ensures the URL is part of the conversation history before the agent attempts to fetch it.

Common gotchas with limited networking#

The most common issue is a 400 error when creating or updating a session. With limited networking, creating a session fails with a 400 error when an enabled web tool's allowed_domains has an entry not within allowed_hosts. A session update that adds such an entry also fails with the same error.

To fix this, you must either add the host to allowed_hosts or remove the entry from allowed_domains. The tool-level allowed_domains list must be a subset of the environment-level allowed_hosts list.

Another gotcha is subdomain matching. An allowed_hosts entry matches one exact host unless it starts with *., so docs.example.com is not within ["example.com"]. You must use *.example.com to match all subdomains, or list each subdomain explicitly.

You can run this Python script to test your host matching logic before deploying an agent. It demonstrates the exact matching rule and the wildcard rule.

def is_host_allowed(host, allowed_hosts):
    for pattern in allowed_hosts:
        if pattern.startswith("*."):
            suffix = pattern[1:]
            if host.endswith(suffix) and len(host) > len(suffix):
                return True
        elif host == pattern:
            return True
    return False

allowed = ["example.com", "*.github.io"]
print(is_host_allowed("docs.example.com", allowed))
print(is_host_allowed("example.com", allowed))
print(is_host_allowed("blog.github.io", allowed))

If you are running agents in self-hosted sandboxes, note that the allowed_hosts restrictions for web_search and web_fetch do not apply. The release notes state that unrestricted networking and self-hosted environments do not limit these tools. If you need similar restrictions in a self-hosted environment, you must enforce them at the network level, such as with egress proxies or firewall rules.

For managing costs while running these agents, the Claude pricing page notes that web search triggered inside a session incurs the standard $10 per 1,000 searches. To keep token costs down, see How to Use Claude Prompt Caching and Read Cache Usage. If you are routing tool traffic through MCP, review How to Build an MCP Server in Python and Test It Locally to ensure your server endpoints are accessible.

Quick reference for web tool policies#

Use this checklist when configuring domain restrictions for your Claude Managed Agents:

1. Check if your environment uses limited networking. If it does, allowed_hosts limits web_search and web_fetch.
2. Add all necessary hosts to allowed_hosts. Remember that allow_package_managers and allow_mcp_servers do not add hosts for these web tools.
3. Use *.domain.com for wildcard subdomain matching in allowed_hosts. Exact matches are required otherwise.
4. Set allowed_domains or blocked_domains on the agent_toolset_20260401 configs array for tool-specific limits.
5. Ensure every entry in a tool's allowed_domains is also in allowed_hosts to avoid 400 errors on session creation.
6. For web_fetch, remember the prior context rule. Provide URLs in user.message events if the agent needs to fetch them.

For the full list of changes and behaviors, see the Claude Platform release notes and the Claude pricing page.

Quick answers