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

A developer documented a one-command method for adding free live web search to Claude Code using the AgentSearch MCP server, installed via `claude mcp add agentsearch -- npx -y @agentsearchhq/agentsearch-mcp`. The setup requires no API key or signup and provides a free `agentsearch_web_search` tool capped at 25 searches per day per IP, with optional paid page extraction and rendering. The guide was tested on Linux with Claude Code 2.1.309, Node.js 20, and `@agentsearchhq/agentsearch-mcp` 1.3.5, and covers local, project, and user scopes for sharing the server across a team or machine.

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 .