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, 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 , globalmcpServers |
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 and Extract 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 is for pages that only show their content after JavaScript runs. See pricing for current rates. If you're new to per-call payments, start with x402 pay-per-call APIs for AI agents.
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 and list what changed this month." For single-page apps, ask for Render. Our guide on reading JavaScript pages from an AI agent 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.
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.
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 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 and Render. Check pricing and the MCP setup page for details, or browse more guides on the AgentSearch blog.
Service pages: Web Search API · Web Extract API · Web Render API
Originally published on the AgentSearch blog.