How does the search work in Claude Code and how to connect the MCP server?

Briefly

• The built-in WebSearch in Claude Code returns only page headers and addresses, and the search engine cannot be replaced. Another search is connected only through the MCP server, and it works next to the built-in one.
• Since version 2.1.212, there is a limit of 200 WebSearch calls per session, including sub-agents. You can't disable it, you can only raise the environment variable.
• Through the Claude API, the search costs $10 per 1000 requests plus tokens. On Amazon Bedrock and most likely through third-party gateways in ANTHROPIC_BASE_URL WebSearch does not work, and then MCP remains the only way to search.
• WebFetch does not give Claude a page, but its retelling by a small model. Before each upload, it checks the domain via api.anthropic.com , therefore, a filtering proxy may not work.
• The MCP server is connected with a single claude mcp add command. Scope determines where the setting is stored and to whom it is visible; it is better to keep the keys in the environment variables.

This is the first of five articles in the series "Free Internet Search for Claude Code". In the series: built-in WebSearch and WebFetch and MCP connection (this article); services with API and free tariff; search without keys and on your server: SearXNG, DuckDuckGo, multi-slide servers; browsers, scrapers, workarounds and services that have stopped working; search from Russia, security, quality, token consumption and a cheat sheet "what to choose". All data was verified on September 17, 2026.

Claude Code is an Anthropic console AI agent for development: it reads and edits code, runs commands and can search for information on the Internet. MCP (Model Context Protocol) is an open protocol through which an agent connects external tools. An MCP server is a program or remote service that, using this protocol, provides an agent with a set of tools: search, page loading, database access. At SystemsLab, we connect such servers when we implement AI agents in companies, and below we have collected what is important to know before choosing a search engine.

Is it possible to replace the search engine in the built-in WebSearch?

No: the WebSearch search backend is not configured, another search is connected only via the MCP server. The Claude Code documentation says this bluntly: "The search backend is not configurable. To search with a different provider, add an MCP server that exposes a search tool» (Tools reference).

WebSearch in Claude Code is a thin client to the server—side search tool Anthropic. The server-side tool means that the search itself is performed on the Anthropic side, and not on your machine. WebSearch returns only the headers and URLs of the results, it does not load the pages themselves. To read the found page, Claude calls WebFetch separately.

In one call, the tool can make up to eight search queries to the backend, clarifying them as it goes. The allowed_domains (search only on these domains) and blocked_domains (exclude these domains) parameters narrow the output, but they cannot be combined in one call. The name of the search index on which the backend works is not officially disclosed by Anthropic.

How many searches can be done in one session?

From version 2.1.212 — no more than 200 WebSearch calls per session, and the limit includes calls from all sub-agents. A subagent is a child agent to whom the main agent assigns part of the work; his searches consume a common counter (Tools reference).

When the limit is exhausted, you will not see this: the next call looks in the dialog like a search that did not give anything, and Claude receives a service instruction to work with the data already collected. The /clear command resets the counter, but if a process that can run subagents continues to run after it, the count is saved. The environment variable CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION raises the limit, but it cannot be turned off at all (Env vars).

In practice, this means that a long research session with several sub-agents can hit the ceiling imperceptibly: the agent will simply stop receiving the results of the built-in search. The MCP server with the search has no effect on this tag.

The WebSearch parameter	The value for September 2026
Session limit	200 calls, since version 2.1.212, including subagents
Backend requests per call	up to 8
How to raise the limit	CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION
How to reset the counter	/clear
Disable the limit	You can't

How much does the built-in search cost?

Through the Claude API, the built-in search costs $10 per 1000 requests plus tokens, and for Pro and Max subscriptions, usage is included in the tariff. The request that ended in an error will not be paid (Pricing; Costs).

No Anthropic page indicates a separate surcharge for the search for Pro and Max subscribers, but there is also no direct phrase " the search is free" in the documentation (not confirmed by the original source). The author of the article on Habré recalculates the embedded search rate as "$0.01 for each query" ("SearXNG + Claude Code: free web search instead of $10 for 1000 queries"). This is the same as the API rate — $10 per 1000 requests — but does not directly apply to the subscription.

How do you work with Claude	The cost of WebSearch
Claude API (payment by usage)	$10 per 1000 requests + tokens; the request with an error will not be paid
Pro or Max subscription	included in the tariff; there is no explicit "free" reservation

Where does WebSearch work and where does it not?

It depends on the provider through which the model is connected: the search works on the Claude API, but not on Amazon Bedrock (Tools reference; Bedrock). The provider here is the platform through which Claude Code accesses the model: Anthropic itself, AWS clouds, Google, Microsoft, or a third—party gateway.

Model Provider	WebSearch
Claude API, Claude Platform on AWS	It works
Google Cloud Agent Platform (Vertex)	works for Claude 4 and newer
Amazon Bedrock	does not work
Microsoft Foundry, deployments from Anthropic	works
Microsoft Foundry hosted in Azure	documentation diverges, it is more reliable to consider non-working
Third-party gateway in ANTHROPIC_BASE_URL (OpenRouter, DeepSeek, GLM, Kimi, local models)	most likely, it does not work: output from the instrument device

According to Foundry in Azure, the sources contradict each other. The Claude Code page says that the WebSearch call fails there, and the API page says that such deployments support the basic version of the tool (Web search tool). Until the contradiction is removed, we would not use the built-in search in this configuration.

ANTHROPIC_BASE_URL is an environment variable that routes Claude Code requests to a different address instead of the Anthropic API. This is how third-party gateways and models of other developers are connected. For such configurations, searching through the MCP becomes the only way to search. There is no direct confirmation in the documentation: this is a conclusion from the fact that WebSearch is an Anthropic server tool, and someone else's gateway will not execute it.

In older versions of the documentation, there was a mention that the search is available only in the USA ("US-only"). It could not be found on the current public pages (not confirmed by the original source).

What does WebFetch actually return?

WebFetch returns to Claude not the page itself, but the response of a "small fast model" that read the page along with your prompt. The documentation calls the tool "lossy by design", that is, lossy by design, and advises you to go through curl (Tools reference) for raw content.

Unlike WebSearch, WebFetch runs on your machine. He downloads the page, turns the HTML into Markdown and passes the result to a small model. Claude gets the response of this model, not the text of the page. This is enough for most tasks, but if you need an exact quote, an entire table, or a snippet of code from the documentation, the retelling may miss something.

The WebFetch parameter	By default	How to change
Cache	15 minutes	CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS
Download timeout	5 minutes	CLAUDE_CODE_WEBFETCH_DEADLINE_MS
Redirect to another host	not executed, it is reported to Claude	not configurable
User-Agent	starts with Claude-User	not configurable

User-Agent is the string that the program is presented to the site. By using the Claude-User prefix, a site can recognize a request from an agent and, for example, restrict it.

Why doesn't WebFetch work behind a corporate proxy?

Because before loading, WebFetch sends the hostname to api.anthropic.com to check the security block list, and if this address is closed, the download is not performed. Only the hostname goes away, without the full URL and page content; the host that has been verified, Claude Code caches for five minutes. Verification takes place at any provider of the model, including through a third-party gateway (Data usage; LLM gateway).

Disabling verification is worthwhile consciously. It checks the domain against the security block list maintained by Anthropic; without it, WebFetch loads any address, so the documentation advises in this case to limit domains to WebFetch rules. In companies where outgoing traffic goes through a proxy, we usually agree with the information security service on a separate rule for this host, rather than turning off the check on all machines.

How can I allow or prohibit search and page loading?

WebSearch is allowed or prohibited only in its entirety by the WebSearch rule, and for WebFetch rules are written by domain. Example of a rule: WebFetch(domain:*.example.com ); domain masks have been working since version 2.1.172. Claude Code writes saved approvals to .claude/settings.local.json (Permissions).

Permissions in Claude Code are allow (allow without a question) and deny (deny) rules, by which the agent decides whether the tool can be called. They have two details that are important to find.

1. Banning WebFetch does not prevent an agent from accessing the same URL via curl in Bash, if Bash is allowed. Banning one tool does not block access to the network entirely.
2. The rules for MCP tools use names like mcp__<server>__<tool>, where server is the name of the MCP server and tool is the name of its tool (Permissions).

When a third-party search is enabled, it is convenient to remove the built-in "deny" rule: ["WebSearch"]. Then Claude will search through the MCP tool and will not choose between two search engines. Example settings.json, where downloads from GitHub subdomains and all searxng server tools are allowed, but embedded search is prohibited:

{ "permissions": {
    "allow": ["WebFetch(domain:*.github.com)", "mcp__searxng"],
    "deny":  ["WebSearch"] } }

How to connect the MCP server to Claude Code?

With one claude mcp add command, the transport, scope, environment variables, and server address or launch command are transferred to it. The general syntax is this (MCP):

claude mcp add [--transport stdio|http|sse] [--scope local|project|user] [--env K=V] [--header "..."] <name> <url | -- command arguments>

Transport is the way Claude Code communicates with the server. stdio is a local server: Claude Code itself runs it as a process and exchanges data through standard input and output. http is a remote server at an address on the Internet; this is the recommended transport. SSE has been deprecated, it is better not to choose it for new connections.

A double hyphen -- separates the Claude Code options from the server startup command: everything after it is passed to the server unchanged.

Typical commands for remote and local server, verification and management:

# remote server
claude mcp add --transport http <name> https://example.com/mcp --header "Authorization:Bearer <key>"
# local stdio server with the key
claude mcp add --scope user --transport stdio --env API_KEY=xxx <name> -- npx -y <package>
# checking and managing
claude mcp list # status ✔/✘
claude mcp get <name>
claude mcp remove <name>
# inside the session: /mcp status and OAuth login

The /mcp command inside the session shows which servers have connected and allows you to log in via OAuth, a standard authorization protocol in which you confirm access in the browser, rather than entering the key into the command.

Which scope should I choose for the MCP server?

Scope local is suitable for personal experiments in one project, project — for general team configuration, user — for the server that you need in all projects. Scope is the scope of the setting: it determines which file the server is stored in and who sees it (MCP; quickstart MCP).

Scope	Where is it stored	Where it operates
local (default)	~/.claude.json (in Windows C:\Users \<Name>\.claude.json)	only in the current project, privately
project	.mcp.json in the project root	everyone who works with the repository; when downloading, Claude Code asks for confirmation
user	~/.claude.json, the mcpServers key	in all your projects

If servers with the same name are set in several places, local wins, followed by project, user, plug-ins and connectors claude.ai . To change the scope, you need to delete the server and add it again: there is no transfer between areas.

In .mcp.json, the substitutions ${VAR} and ${VAR:-default} work, where default is the value in case the variable is not specified. Therefore, the key can be kept in the environment variable, and not in the file that gets into git. For team configuration with a paid search API, this is a mandatory practice: .mcp.json is in the repository and is visible to everyone who has access to it.

What other settings affect the search via MCP?

Three: the MCP-tool response size limit, tool search mode, and launch features on Windows. Each of them can imperceptibly break the search.

• The output of the MCP tool is limited to 25,000 tokens, and when more than 10,000 tokens are output, a warning appears. The limit is raised by the variable MAX_MCP_OUTPUT_TOKENS; everything that exceeds the limit is saved to a file (MCP). For search servers that return the full text of pages, this limitation is achieved quickly.
• Tool search is a mode in which Claude Code delays loading descriptions of MCP tools and loads them as needed, saving context. It is enabled by default, but automatically turns off if ANTHROPIC_BASE_URL points to a third-party host. You can return it to the ENABLE_TOOL_SEARCH (MCP) variable. Without the search tool, descriptions of all connected servers immediately take up space in the context.
• Windows. On the current documentation page there is no requirement to wrap npx in cmd/c, and in version 2.1.119 the false warning about this (CHANGELOG) was removed. Nevertheless, if the stdio server crashes with the "Connection closed" error, the --cmd /c npx -y <package> option still often helps (not confirmed by up-to-date documentation).

Where to look for MCP servers?

In the Anthropic Directory (claude.ai/directory ) and in the official register registry.modelcontextprotocol.io . Claude Code itself refers to the Anthropic Directory: proven connectors are collected there, and any remote server from there is added via claude mcp add (MCP).

Vendor-neutral official registry registry.modelcontextprotocol.io , that is, not tied to a single model supplier, launched in preview mode on September 8, 2025 (MCP blog, "Introducing the MCP Registry"). It was not possible to establish whether he left the preview by September 2026.

Before connecting a server from any directory, it's worth looking at who its author is and what permissions it asks for. The search server brings text from other people's sites into the agent's context, and this text may contain instructions for the model. Details about such attacks — prompt injection and tool poisoning — will be discussed in the final article of the series.

Why do I need a Fetch reference server?

Fetch is useful as a replacement for WebFetch when an agent needs raw page text without retelling. This is one of the seven reference servers in the modelcontextprotocol/servers repository; the developers emphasize that the reference servers are training implementations, not production solutions (servers). Brave Search and Puppeteer servers from the same repository have been moved to the archive.

Fetch works without a key. It does not search for anything, but only gives the page to Markdown in chunks: the max_length parameter sets the size of the chunk (5000 characters by default), start_index — which character to start with. By default, the server respects robots.txt — a file in which the site indicates that robots can upload — if the request was initiated by the model (fetch README).

The README warns that the server may access local and internal IP addresses. If the agent works on a corporate network, Fetch can theoretically read internal services, so such a server should be run in an isolated environment — for example, in a separate container on a company server with limited network access.

Fetch (reference)	Value
Access	without a key
What does	loads the page and gives Markdown chunks, does not search
Parameters	max_length, start_index
robots.txt	complies with the default
Risk	can access local and internal IP (according to the project README)

Connection with one command (you need an installed uv, from which uvx is taken):

claude mcp add fetch -- uvx mcp-server-fetch

Fetch closes the task of reading pages, but not searching. Which search services provide an API with a free tariff, what they have is updated every month, and what is issued on a one-time basis, we will discuss in the next article in the series. If you want to connect search to agents in your company, taking into account rights and network restrictions, we do this as part of the development and implementation of AI agents.

Sources

1. Tools reference: WebSearch behavior tool — code.claude.com , verified on 09/17/2026.
2. Tools reference: Session search limit — code.claude.com , verified on 09/17/2026.
3. Environment variables — code.claude.com , verified on 09/17/2026.
4. Pricing — platform.claude.com , verified on 09/17/2026.
5. Costs — code.claude.com , verified on 09/17/2026.
6. SearXNG + Claude Code: Free web search instead of $10 for 1000 queries — habr.com , verified on 09/17/2026.
7. Claude Code on Amazon Bedrock — code.claude.com , verified on 09/17/2026.
8. Web search tool — platform.claude.com , verified on 09/17/2026.
9. Tools reference: WebFetch tool behavior — code.claude.com , verified on 09/17/2026.
10. Data usage: WebFetch domain safety check — code.claude.com , verified on 09/17/2026.
11. LLM gateway protocol — code.claude.com , verified on 09/17/2026.
12. Permissions: WebFetch — code.claude.com , verified on 09/17/2026.
13. Permissions — code.claude.com , verified on 09/17/2026.
14. Connect Claude Code to tools via MCP — code.claude.com , verified on 09/17/2026.
15. MCP quickstart — code.claude.com , verified on 09/17/2026.
16. MCP: Configure tool search — code.claude.com , verified on 09/17/2026.
17. Claude Code CHANGELOG — github.com , verified on 09/17/2026.
18. Introducing the MCP Registry — blog.modelcontextprotocol.io , verified on 09/17/2026.
19. modelcontextprotocol/servers — github.com , verified on 09/17/2026.
20. Fetch MCP Server, README — github.com , verified on 09/17/2026.