# How to Add Free Web Search to Claude Code with MCP (No API Key)

> Source: <https://dev.to/agentsearchhq/how-to-add-free-web-search-to-claude-code-with-mcp-no-api-key-3bfo>
> Published: 2026-10-23 20:35:10+00:00

Claude Code is great at reading your repo, but it can't see the live web on its own unless you give it a tool. The quickest way to add **web search to Claude Code** is an **MCP** server. This guide sets up MCP web search for Claude Code with one `claude mcp add` command. You don't need an API key, a signup, or a config file. An optional wallet key adds paid page extraction and rendering later (search stays free by default even then).

We'll use [AgentSearch](https://agentsearchhq.com/?utm_source=devto&utm_medium=referral&utm_campaign=add-web-search-to-claude-code-mcp), which ships as the `@agentsearchhq/agentsearch-mcp` package on npm and is listed in the official MCP Registry. Out of the box it gives Claude Code a free `agentsearch_web_search` tool:

Free tier: up to 25 searches/day per IP, no key needed (shared daily capacity; paid calls have no cap).

**What we tested:** every command below was run on Linux with Claude Code 2.1.309, Node.js 20, and `@agentsearchhq/agentsearch-mcp` 1.3.5. We also ran the server directly over stdio to confirm the tool list, a free search, that search stays free even with a wallet key set (and only becomes paid with `AGENTSEARCH_MODE=paid`), and the no-wallet messages for Extract and Render.

`claude --version` should print a version).`npx` on your PATH (`node -v`). The MCP server runs through From your project directory, run:

```
claude mcp add agentsearch -- npx -y @agentsearchhq/agentsearch-mcp
```

Claude Code should answer with something like:

```
Added stdio MCP server agentsearch with command: npx -y @agentsearchhq/agentsearch-mcp to local config
```

Here's what each part of that command does:

`agentsearch` is the server name. Claude Code uses it to name the tools, so they show up as `mcp__agentsearch__agentsearch_web_search` and so on.`--` separates Claude Code's own flags from the command it should launch. Everything after it is passed to the server unchanged, which keeps `-y` from being read as a Claude Code option.`npx -y @agentsearchhq/agentsearch-mcp` downloads and starts the server. The The transport is **stdio**, which is the default for `claude mcp add`. Claude Code starts the server as a local child process and talks to it over stdin/stdout, so there's no port or URL to manage.

`claude mcp add` accepts `--scope` (or `-s`) with three values:

| Scope | Where it's stored | Who gets it | 
|---|---|---|
| `local` (default) | `~/.claude.json` , under this project's path | Only you, only in this project | 
| `project` | `.mcp.json` in the project root | Everyone who clones the repo | 
| `user` | `~/.claude.json` , global`mcpServers` | Only you, in every project | 

**Share with your team.** To check the server into git so everyone on the team gets web search:

```
claude mcp add --scope project agentsearch -- npx -y @agentsearchhq/agentsearch-mcp
```

That writes this `.mcp.json` file to the project root:

```
{
  "mcpServers": {
    "agentsearch": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@agentsearchhq/agentsearch-mcp"],
      "env": {}
    }
  }
}
```

You can also write the file by hand and commit it. For security, Claude Code asks each person to approve project-scoped servers the first time they open the project. Until they do, `claude mcp list` shows the server as `⸠Pending approval`. If someone declines by mistake, `claude mcp reset-project-choices` brings the prompt back.

**Use it everywhere.** To have web search in every project on your machine:

```
claude mcp add --scope user agentsearch -- npx -y @agentsearchhq/agentsearch-mcp
```

If the same name exists in more than one scope, local wins over project, and project wins over user.

Outside a session, run:

```
claude mcp list
```

You should see:

```
agentsearch: npx -y @agentsearchhq/agentsearch-mcp - ✔ Connected
```

For details on one server (its scope, command, and environment variables), run `claude mcp get agentsearch`. Inside a Claude Code session, type `/mcp` to see every server, its status, and its tools.

The server exposes five tools:

`agentsearch_web_search`: web search that returns up to 5 results (title, URL, and a content snippet). This is free with no configuration.`agentsearch_extract`: reads a URL and returns clean markdown or text. This is paid and needs a wallet.`agentsearch_render`: loads a JavaScript-heavy page in a headless browser and returns markdown, text, HTML, links, or a screenshot. This is paid and needs a wallet.`agentsearch_review_lookup` and `agentsearch_review_submit`: read and share agent-written reviews of web tools.
Start `claude` in your project and ask for something that needs current information. Claude Code decides on its own when to call the tool, and it asks for permission the first time. Here are some prompts that work well:

```
Search the web for the latest stable release of Vite and tell me if our package.json is behind.
Use agentsearch to find the official migration guide for Express 5, then list the breaking changes that affect src/server.ts.
Search for "MCP stdio transport specification" and summarize how servers should handle stderr.
Find three recent docs pages about the Node.js test runner and give me the URLs.
```

To skip the permission prompt for search, add an allow rule to `.claude/settings.json`:

```
{
  "permissions": {
    "allow": ["mcp__agentsearch__agentsearch_web_search"]
  }
}
```

Search results are snippets. When Claude needs a whole page, that's what Extract and Render are for.

[Search](https://agentsearchhq.com/search?utm_source=devto&utm_medium=referral&utm_campaign=add-web-search-to-claude-code-mcp) and [Extract](https://agentsearchhq.com/extract?utm_source=devto&utm_medium=referral&utm_campaign=add-web-search-to-claude-code-mcp) cost $0.005 per call on the Pocket Agentic Portal. Payment is in USDC over x402 on Base or MPP on Tempo, with no signup, no API key, and no minimums. [Render](https://agentsearchhq.com/render?utm_source=devto&utm_medium=referral&utm_campaign=add-web-search-to-claude-code-mcp) is for pages that only show their content after JavaScript runs. See [pricing](https://agentsearchhq.com/pricing?utm_source=devto&utm_medium=referral&utm_campaign=add-web-search-to-claude-code-mcp) for current rates. If you're new to per-call payments, start with [x402 pay-per-call APIs for AI agents](https://agentsearchhq.com/blog/x402-pay-per-call-api-for-ai-agents?utm_source=devto&utm_medium=referral&utm_campaign=add-web-search-to-claude-code-mcp).

The MCP server pays over x402 with USDC on Base. You give it a key for a **new, dedicated wallet** that holds only a small amount of USDC. The server signs exact USDC payments to the portal only, and needs no ETH for gas.

**Search stays free by default, even with a wallet key.** In version 1.3.5, setting a wallet key only turns on paid Extract and Render. `agentsearch_web_search` keeps using the free relay (up to 25 searches/day per IP) unless you also set `AGENTSEARCH_MODE=paid`, which makes search a paid call too, or `AGENTSEARCH_MODE=auto`, which also opts into paid search when a wallet key is set. Leave the mode unset (or set `AGENTSEARCH_MODE=free`) to keep search free. On 1.3.4 and earlier, a wallet key made search paid as well, so update with `npx -y @agentsearchhq/agentsearch-mcp@latest` if you see that.

The example below adds a separate server so the key lives on only one server and your Step 1 server stays key-free. You can also put the same `--env` flags on your main server.

```
claude mcp add agentsearch-paid \
  --env AGENTSEARCH_WALLET_PRIVATE_KEY=0xYOUR_DEDICATED_WALLET_KEY \
  --env AGENTSEARCH_MAX_TOTAL_ATOMIC=50000 \
  -- npx -y @agentsearchhq/agentsearch-mcp
```

Keep the server name *before* the `--env` flags. If the name comes right after an `--env` value, the CLI can read it as another `KEY=value` pair.

**Spend caps.** The server enforces these limits before it signs anything:

`AGENTSEARCH_MAX_TOTAL_ATOMIC` sets the total spend per server session, in USDC atomic units (1000000 = $1.00). The default is $1.00, and the example above sets $0.05. It has to be a whole number. The count resets when the server restarts.`AGENTSEARCH_MAX_PER_CALL_ATOMIC` sets a per-call ceiling. You can only lower it.
When a cap is reached, the tool returns `Session spend cap reached ... Nothing was signed.` instead of paying.

**Don't commit keys.** For a project-scoped paid server, put a variable reference in `.mcp.json` and keep the real key in your shell:

```
{
  "mcpServers": {
    "agentsearch-paid": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@agentsearchhq/agentsearch-mcp"],
      "env": {
        "AGENTSEARCH_WALLET_PRIVATE_KEY": "${AGENTSEARCH_WALLET_PRIVATE_KEY}",
        "AGENTSEARCH_MAX_TOTAL_ATOMIC": "${AGENTSEARCH_MAX_TOTAL_ATOMIC:-50000}"
      }
    }
  }
}
```

Claude Code expands `${VAR}` and `${VAR:-default}` when it starts the server.

One related gotcha: stdio servers inherit the environment of the shell that launched `claude`. If you `export AGENTSEARCH_WALLET_PRIVATE_KEY` globally, your key-free server picks it up too. Search still stays free on 1.3.5 unless `AGENTSEARCH_MODE` is `paid` or `auto`, but Extract and Render on that server can now sign payments. Set the key only on the server that should pay, and check that `AGENTSEARCH_MODE` isn't exported unless you want paid search.

Once Extract is set up, try a prompt like *"Extract [https://example.com/docs/changelog](https://example.com/docs/changelog) and list what changed this month."* For single-page apps, ask for Render. Our guide on [reading JavaScript pages from an AI agent](https://agentsearchhq.com/blog/read-javascript-pages-from-ai-agent?utm_source=devto&utm_medium=referral&utm_campaign=add-web-search-to-claude-code-mcp) explains when you need each one.

**`✘ Failed to connect` on the first run.** The first `npx` run downloads the package, which can take longer than Claude Code's startup timeout. Run `claude mcp list` again, or start a session with a longer timeout:

```
MCP_TIMEOUT=60000 claude
```

**See the actual error.** Run the server by itself: `npx -y @agentsearchhq/agentsearch-mcp`. A healthy server prints a "listening on stdio" line to stderr and then waits for input (press Ctrl+C to stop). Errors like `npx: command not found` or an unsupported engine mean you need Node.js 20+ on the PATH that Claude Code sees. With nvm or similar tools, the shell you start `claude` from matters.

**Windows.** In WSL, use the commands above as written. On native Windows, if the server won't start because `npx` can't be launched directly, wrap it in `cmd /c`:

```
claude mcp add agentsearch -- cmd /c npx -y @agentsearchhq/agentsearch-mcp
```

**The env var isn't reaching the server.** Run `claude mcp get agentsearch-paid` and check the `Environment` section. If it's missing, the `--env` flags were probably in the wrong place (see the note in Step 5). Remove and re-add the server: `claude mcp remove agentsearch-paid -s local`. For `${VAR}` references in `.mcp.json`, make sure the variable is exported in the shell that starts `claude`.

**Search is charging me (or says it needs payment).** Check `AGENTSEARCH_MODE` in the server's environment. Search is free unless it is `paid` or `auto` with a wallet key set. Unset it, or set `AGENTSEARCH_MODE=free`, and restart the session. If you're on 1.3.4 or earlier, a wallet key makes search paid; run `npx -y @agentsearchhq/agentsearch-mcp@latest` to pick up 1.3.5.

**Extract or Render says "paid tool ... No wallet is configured".** That's expected on the free server. Nothing was charged. Add the paid server from Step 5, or stick with search.

**The tool isn't showing in `/mcp`.** Check these in order:

`⸠Pending approval` in `claude mcp list`.` claude mcp get agentsearch` shows the scope.`.mcp.json`?
If a tool shows up but Claude never uses it, name it in the prompt ("use agentsearch to...").

For retry and fallback patterns once your agent depends on these tools, see [error handling for AI agent web tools](https://agentsearchhq.com/blog/error-handling-ai-agent-web-tools?utm_source=devto&utm_medium=referral&utm_campaign=add-web-search-to-claude-code-mcp).

`claude mcp add pocket-portal -- npx -y @pocket-network/agentic-portal-mcp` connects Claude Code to the Pocket Agentic Portal, where AgentSearch is one of the listed services.`agentsearchhq/agentsearch-mcp` (`smithery.ai/servers/agentsearchhq/agentsearch-mcp`).` claude mcp add-json agentsearch '{"type":"stdio","command":"npx","args":["-y","@agentsearchhq/agentsearch-mcp"]}'` does the same thing as Step 1.
More clients and options are on the [AgentSearch MCP page](https://agentsearchhq.com/mcp?utm_source=devto&utm_medium=referral&utm_campaign=add-web-search-to-claude-code-mcp).

No. The `claude mcp add` command in Step 1 needs no key, no account, and no config. Free tier: up to 25 searches/day per IP, no key needed (shared daily capacity; paid calls have no cap).

Not by default. On 1.3.5, search stays free with a wallet key set. Only `AGENTSEARCH_MODE=paid` (or `auto`) opts into paid search at $0.005 per call. Extract and Render are the calls that use the wallet.

Up to 5 per call. You can ask for fewer (`max_results` from 1 to 5), and Claude Code often does that on its own for narrow questions.

Yes. If you want to call search over plain HTTP from your own code, see the [free web search API](https://agentsearchhq.com/free-web-search-api?utm_source=devto&utm_medium=referral&utm_campaign=add-web-search-to-claude-code-mcp) page.

Yes. Use `--scope project` to write a `.mcp.json`, commit it, and each teammate approves it once. Keep wallet keys out of the file with `${VAR}` references.

The paid tools stop signing and return a "Session spend cap reached ... Nothing was signed." message. Raise `AGENTSEARCH_MAX_TOTAL_ATOMIC` and restart the server (or the Claude Code session) to continue.

Web content isn't trusted input. A page can contain text written to steer an AI. Keep Claude Code's permission prompts on for anything that edits files or runs commands, and review what it proposes after reading external pages.

Run `claude mcp remove agentsearch -s local` (or `-s project` / `-s user`, matching where you added it).

Run `claude mcp add agentsearch -- npx -y @agentsearchhq/agentsearch-mcp`, then `claude mcp list`, and ask Claude Code a question about something that changed last week. When you need full pages, add a capped paid server for [Extract](https://agentsearchhq.com/extract?utm_source=devto&utm_medium=referral&utm_campaign=add-web-search-to-claude-code-mcp) and [Render](https://agentsearchhq.com/render?utm_source=devto&utm_medium=referral&utm_campaign=add-web-search-to-claude-code-mcp). Check [pricing](https://agentsearchhq.com/pricing?utm_source=devto&utm_medium=referral&utm_campaign=add-web-search-to-claude-code-mcp) and the [MCP setup page](https://agentsearchhq.com/mcp?utm_source=devto&utm_medium=referral&utm_campaign=add-web-search-to-claude-code-mcp) for details, or browse more guides on the [AgentSearch blog](https://agentsearchhq.com/blog/?utm_source=devto&utm_medium=referral&utm_campaign=add-web-search-to-claude-code-mcp).

Service pages: [Web Search API](https://agentsearchhq.com/search?utm_source=devto&utm_medium=referral&utm_campaign=add-web-search-to-claude-code-mcp) · [Web Extract API](https://agentsearchhq.com/extract?utm_source=devto&utm_medium=referral&utm_campaign=add-web-search-to-claude-code-mcp) · [Web Render API](https://agentsearchhq.com/render?utm_source=devto&utm_medium=referral&utm_campaign=add-web-search-to-claude-code-mcp)

*Originally published on the [AgentSearch blog](https://agentsearchhq.com/blog/add-web-search-to-claude-code-mcp?utm_source=devto&utm_medium=referral&utm_campaign=add-web-search-to-claude-code-mcp).*