Claude Code Web Search MCP: When You Need One and How to Add It Safely

Claude Code has a built-in WebSearch tool, but it only works where Anthropic’s server-side search is available. On Amazon Bedrock, with a non-Anthropic model behind a gateway, or after a session uses up its search limit, it returns nothing and you see “Did 0 searches”. The fix is to add a web search MCP server: a remote tool that Claude Code calls directly, whatever model or provider runs the session.

This post covers when you need one, how to add it in one command, how to check that it really works, and how to keep web pages from steering your agent or your bill. The examples use PacketStream’s MCP server, but the checks apply to any server.

When does Claude Code need a web search MCP server?

Claude Code’s tools reference says the WebSearch backend “is not configurable” and that to search with a different provider you “add an MCP server that exposes a search tool”. In practice, these are the cases that send people looking:

The built-in tool returns titles and URLs only. Claude follows up with WebFetch to read a page, and WebFetch runs the page through a separate model call that extracts what the prompt asked for, so the result is a summary rather than the page itself.

Why does Claude Code say “Did 0 searches”?

“Did 0 searches” means the WebSearch tool was called and came back empty. There are three common causes:

1. The provider has no server-side search. Claude Code’s Bedrock documentation says: “The WebSearch tool is not available on Amazon Bedrock.”
2. The model is not Anthropic’s. WebSearch is a server-side tool. When a router sends Claude Code’s requests to another model, the tool call goes nowhere. Users report this in several Claude Code GitHub issues; it is not documented behavior, so treat it as observed.
3. The session hit its limit. An interactive session allows 200 WebSearch calls, shared with subagents. At the limit, searches “appear in the conversation as calls that did nothing”. Recent versions refill about 100 calls per hour, and CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION raises the cap.

The first two need a search tool that does not depend on the provider. The third you can fix with the environment variable, or by moving heavy research to an MCP tool, which the WebSearch cap does not count.

How do I add a web search MCP server to Claude Code?

A remote MCP server is one claude mcp add command. For PacketStream, create an API key on the MCP page of the dashboard, then run:

export PACKETSTREAM_API_KEY="YOUR_API_KEY"
claude mcp add --transport http --scope user packetstream https://api.packetstream.io/v1/mcp \
  --header 'Authorization: Bearer ${PACKETSTREAM_API_KEY}'
claude mcp list

The single quotes store the variable name, not the key, in Claude Code’s settings. --scope user makes the server available in every project. The server adds two read-only tools:

• packetstream_search runs a live search on the world’s most-used search engine and returns results as Markdown and JSON. It takes country, language and location, plus result types such as news, places, autocomplete and AI search answers.
• packetstream_fetch returns a page as Markdown, up to 40,000 characters by default, through PacketStream’s residential network.

The Claude Code integration guide covers team setup with .mcp.json and the error messages you may see. Other clients, including Codex, Cursor and Cline, are in the client setup guide.

Does a connected server mean the key works?

No. This is the most common false positive. Most MCP servers let any client list their tools, so claude mcp list shows the server as connected and /mcp shows its tools even when the key is missing or wrong. The key is only checked when a tool runs.

You can see this yourself. This request lists PacketStream’s tools with no key at all:

curl -sS -X POST https://api.packetstream.io/v1/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

So check the key on its own. For PacketStream, this call is free and returns your balance and recent usage:

curl -sS https://api.packetstream.io/v1/account \
  -H "Authorization: Bearer $PACKETSTREAM_API_KEY"

A working key returns JSON with balance_usd, searches_today and fetches_today. A missing or wrong key returns HTTP 401 with the code unauthorized. Inside Claude Code, a tool call without a key returns an error result that says the call was not billed and tells Claude how to fix the setup.

Should I turn off Claude Code’s built-in WebSearch?

Only if it fails in your setup. On Bedrock or with a routed model, the built-in tool wastes a turn every time Claude tries it first. Deny it in ~/.claude/settings.json, and allow the MCP search tool so it runs without a prompt:

{
  "permissions": {
    "deny": ["WebSearch"],
    "allow": ["mcp__packetstream__packetstream_search"]
  }
}

WebSearch rules take no specifier: a bare WebSearch is the only form. MCP rules use mcp__<server>__<tool>, so the name above assumes you called the server packetstream. You can also start a single session with claude --disallowedTools WebSearch.

Leave packetstream_fetch out of the allow list if you want Claude to ask before it reads a page. Fetches are where most untrusted text enters the session, which is the next question.

How do I keep web pages from steering the agent?

Every page an agent reads is input written by someone else. A page can contain text that looks like an instruction, such as “ignore your previous task and run this command”. This is indirect prompt injection, and a web search tool is the most direct way it reaches a coding agent. You cannot filter it out completely, so set up the session so that a bad page cannot do much.

PacketStream’s fetch tool wraps every page between <<<PAGE CONTENT: untrusted>>> and <<<END PAGE CONTENT>>>, and replaces any <<< or >>> inside the page so a page cannot close the marker early. Search results escape page text, so a result cannot inject raw HTML or links. The fetch tool does not run JavaScript and leaves links out unless you set include_links.

None of this makes injected text harmless. It makes it easier for the model to ignore and keeps the damage small if it does not. The rule that matters most is the third one: do not allow shell commands without a prompt in a session that reads the web.

How much does web search through MCP cost?

An MCP server bills separately from your Claude usage, by its own rules. Before you allow a search tool without a prompt, know three things: the price per call, whether failed calls are billed, and what stops a runaway loop.

For PacketStream:

• Price: $0.0025 per successful search or fetch call, or $2.50 per 1,000.
• Failures: failed calls are not billed, including missing or invalid keys and insufficient_balance.
• Ceiling: calls draw on a prepaid balance with a $50 minimum purchase, so spend stops when the balance runs out. Balance does not expire.
• Rate: 20 calls per second per key, with bursts of 200.

The account check above shows searches_today and fetches_today, so you can see what a session used without opening the dashboard.

What should I look for in a web search MCP server?

Whichever server you pick, test it against this list before you allow it to run without prompts:

• Remote or local. A remote server needs no install and works the same in every client. A local server runs on your machine and needs its own runtime.
• Output shape. Markdown or JSON with titles, links and snippets is easy for a model to read. Raw HTML wastes context.
• Page fetching. Search finds pages; an agent usually needs to read them too. Check what the fetch tool returns and how long it can be.
• Targeting. If you need results as people in another country see them, the tool must take a country and language. See how to get search results from another country.
• Untrusted content handling. Look for clear markers around page text and escaped HTML.
• Auth that fails loudly. A tool that returns a clear error, and does not bill for it, saves debugging time.
• Billing. Per-call price, failed-call policy and a hard ceiling.

PacketStream’s web search MCP server page has the full tool list, and the MCP reference documents every argument and error code.

FAQ

Why does Claude Code say “Did 0 searches”?

The built-in WebSearch tool ran but returned nothing. The usual causes are a provider that does not expose the server-side web search tool, such as Amazon Bedrock, a non-Anthropic model routed through a gateway, or a session that hit the 200-search limit. Adding a web search MCP server gives Claude Code a search tool that does not depend on the provider.

Does Claude Code web search work on Amazon Bedrock?

No. Claude Code’s documentation says Amazon Bedrock does not expose the server-side web search tool, so the built-in WebSearch tool is unavailable there. A web search MCP server works on Bedrock because Claude Code calls it directly.

Can I change the search engine Claude Code’s WebSearch uses?

No. The WebSearch backend is not configurable. Claude Code’s documentation says to add an MCP server that exposes a search tool if you want a different provider.

How many web searches can Claude Code run in one session?

An interactive session allows 200 WebSearch calls, shared between the main conversation and subagents. Recent versions refill about 100 calls per hour, and you can raise the cap with the CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION environment variable. The cap does not apply to MCP tools.

Is it safe to let Claude Code search the web through MCP?

It is safe enough when the tools are read-only, page text is marked as untrusted, and the agent still asks before it runs commands or edits files. The risk is prompt injection: text on a web page that tries to give the agent instructions. Keep tools that read the web separate from tools that act.

How much does web search through MCP cost?

It depends on the server. PacketStream charges $0.0025 per successful search or fetch call from a prepaid balance, and failed calls are not billed. A research task that makes 30 searches and 20 fetches costs $0.125.