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

A developer documented a setup for adding free web search to the Cursor code editor through the Model Context Protocol, using a single mcp.json entry pointing at the @agentsearchhq/agentsearch-mcp npm package with no API key, signup, or extension required. The writeup covers global versus project-level config, tool approval via the Cursor CLI, keeping wallet keys out of git, and Windows path fixes, and reports testing version 1.3.5 on Linux with Node.js 20 over stdio, confirming the tool list, a free search, no-wallet messages for Extract and Render, and the spend cap. The free tier allows up to 25 searches per day per IP, with an optional wallet key enabling paid page extraction and rendering.

Cursor's agent knows your codebase, but it can't check today's docs, release notes, or error threads unless you give it a tool. This guide sets up Cursor MCP web search with one entry in an mcp.json file, with no API key, signup, or extension. We'll cover global vs project config, tool approval, keeping wallet keys out of git, and Windows fixes. An optional wallet key adds paid page extraction and rendering later, and 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-cursor-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 Cursor 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: we ran @agentsearchhq/agentsearch-mcp 1.3.5 on Linux with Node.js 20 over raw stdio to confirm the tool list, a free search, the no-wallet messages for Extract and Render, and the spend cap. We loaded every config below with the Cursor CLI agent 2026.10.22 , which reads the same mcp.json files as the editor. The editor screens we mention come from Cursor's documentation. Using Claude Code too? See add web search to Claude Code with MCP https://agentsearchhq.com/blog/add-web-search-to-claude-code-mcp?utm source=devto&utm medium=referral&utm campaign=add-web-search-to-cursor-mcp . npx on your PATH node -v . Cursor starts the server with Cursor reads MCP servers from two files: | File | Scope | Good for | |---|---|---| | ~/.cursor/mcp.json | Global: every project on your machine | Tools you want everywhere, and anything with a secret | | .cursor/mcp.json in the project root | Project: this repo only | Tools you want to share with the team through git | For web search you usually want it everywhere, so create or open ~/.cursor/mcp.json on Windows that's %USERPROFILE%\.cursor\mcp.json and add: { "mcpServers": { "agentsearch": { "type": "stdio", "command": "npx", "args": "-y", "@agentsearchhq/agentsearch-mcp" } } } If the file already has servers, add the "agentsearch" block inside the existing mcpServers object. agentsearch is the server name shown in Cursor and the CLI. "type": "stdio" tells Cursor to start the server as a local process and talk over stdin/stdout. No port, URL, or OAuth. command and args run npx -y @agentsearchhq/agentsearch-mcp . The -y skips npx's install prompt, which nobody could answer for a background process. No env block is needed for free search. To commit web search to a repo so every teammate gets it, put the same JSON in .cursor/mcp.json at the project root and commit the file. Two things we confirmed with the Cursor CLI: not loaded needs approval until we approved it with agent mcp enable agentsearch , so a cloned repo can't start processes without your OK. Never put a wallet key in a committed project file. Step 5 shows how to reference it instead. In the editor, open Customize in the sidebar. Cursor's docs say that's where you enable or disable MCP servers, and each server has a toggle. Make sure agentsearch is on. If you have the Cursor CLI installed, you can also check from a terminal: agent mcp list agentsearch: ready And to see the tools: agent mcp list-tools agentsearch Tools for agentsearch 5 : - agentsearch extract url, formats, max chars - agentsearch render url, formats, max chars, screenshot, screenshot format, full page, viewport, wait until, wait for selector, wait ms, block - agentsearch review lookup task, service id, max price usd, network, limit, include down - agentsearch review submit service id, success, task, latency ms, quality, price paid usd, note, called at, proof tx hash, pocket session id - agentsearch web search query, max results What the five tools do: agentsearch web search : web search that returns up to 5 results title, URL, and a passage of page text . 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. These are free. According to Cursor's docs, the agent uses MCP tools listed under Available Tools on its own when they're relevant, and that includes Plan Mode. You can also ask for a tool by name. Prompts like these work well: Search the web for the current stable version of Next.js and tell me whether package.json is behind. Use agentsearch to find the official migration guide for ESLint flat config, then list what we need to change in our .eslintrc. Tool approval. By default, Cursor asks for approval before it runs an MCP tool. Click the arrow next to the tool name to see the arguments; for search that's just the query and max results . MCP tools follow the same Run Modes as terminal commands, so only pre-approve tools you're comfortable running unattended. The search tool marks itself read-only in its MCP annotations. Here's a trimmed result from a real call to agentsearch web search with max results: 1 : { "query": "cursor mcp", "result count": 1, "results": { "title": "Model Context Protocol MCP | Cursor Docs", "url": "https://cursor.com/docs/mcp", "content": "Model Context Protocol MCP enables Cursor to connect to external tools and data sources...", "domain": "cursor.com" } } Results are passages, not whole pages. For full pages, use Extract and Render. Search https://agentsearchhq.com/search?utm source=devto&utm medium=referral&utm campaign=add-web-search-to-cursor-mcp and Extract https://agentsearchhq.com/extract?utm source=devto&utm medium=referral&utm campaign=add-web-search-to-cursor-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-cursor-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-cursor-mcp for current rates. If per-call payments are new to you, read 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-cursor-mcp first. The MCP server pays over x402 with USDC on Base. You give it the key for a new, dedicated wallet that holds only a small amount of USDC. It 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 1.3.5, a wallet key only turns on paid Extract and Render. agentsearch web search stays on the free tier 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 it to free to keep search free. Don't paste the key into mcp.json . Cursor's config supports ${env:NAME} interpolation in env values, so the file only holds a reference: { "mcpServers": { "agentsearch": { "type": "stdio", "command": "npx", "args": "-y", "@agentsearchhq/agentsearch-mcp" , "env": { "AGENTSEARCH WALLET PRIVATE KEY": "${env:AGENTSEARCH WALLET PRIVATE KEY}", "AGENTSEARCH MAX TOTAL ATOMIC": "50000" } } } } Set AGENTSEARCH WALLET PRIVATE KEY in the environment Cursor starts from, restart Cursor, and keep this entry in your global ~/.cursor/mcp.json . Spend caps. The server checks these limits before it signs anything: AGENTSEARCH MAX TOTAL ATOMIC is 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 must be a whole number, and the count resets when the server restarts. AGENTSEARCH MAX PER CALL ATOMIC is 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. Once Extract works, 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-cursor-mcp explains when you need each one. Read the MCP logs first. Cursor's docs point to the Output panel Cmd+Shift+U , then MCP Logs in the dropdown. It shows server startup, tool calls, and errors. Run the server by itself. Run npx -y @agentsearchhq/agentsearch-mcp in a terminal. A healthy server prints agentsearch-mcp listening on stdio to stderr and waits for input Ctrl+C to stop . On npx: command not found or an engine error, install Node.js 20+. With nvm or similar tools, put the full path to npx in command . Windows. If the logs show that npx can't be started, wrap it in cmd /c : { "mcpServers": { "agentsearch": { "type": "stdio", "command": "cmd", "args": "/c", "npx", "-y", "@agentsearchhq/agentsearch-mcp" } } } In JSON, Windows paths need doubled backslashes C:\\Program Files\\nodejs\\npx.cmd . A single backslash makes the whole file invalid. Nothing loads after you edit the file. Check for valid JSON one mcpServers object, no trailing commas , that the toggle is on in Customize, and, for project configs, that you approved it. Extract says "AGENTSEARCH WALLET PRIVATE KEY is set but is not a private key". In our CLI test, a ${env:...} reference to a variable that wasn't set reached the server as the literal text ${env:AGENTSEARCH WALLET PRIVATE KEY} . Set the variable where Cursor starts, then restart Cursor. Nothing is signed in this case, and search keeps working. Extract or Render says "paid tool ... No wallet is configured". That's expected without a key. No call was made and nothing was charged. Search returns "AGENTSEARCH MODE must be one of 'free', 'paid' or 'auto'". Fix the typo in env or remove the variable. Updating the server. npx -y runs the cached copy. Cursor's docs suggest removing the server, running npm cache clean --force , and adding it again to get the latest version. 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-cursor-mcp . npx -y @pocket-network/agentic-portal-mcp connects Cursor to the Pocket Agentic Portal, where AgentSearch is one of the listed services. agentsearchhq/agentsearch-mcp . 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-cursor-mcp . No. The config in Step 1 has no key, no account, and no env block. Free tier: up to 25 searches/day per IP, no key needed shared daily capacity; paid calls have no cap . Use the global ~/.cursor/mcp.json for tools you want in every project and for anything that involves a wallet key. Use the project .cursor/mcp.json when you want the whole team to get web search from the repo. If both define the same server name, the project one wins. Not by default. In 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. The agent can ask for fewer with max results 1 to 5 . Yes. The CLI uses the same MCP configuration as the editor, and we tested these configs with agent mcp list . Treat web content as untrusted input, because a page can contain text written to steer an AI. Keep approval on for tools that edit files or run commands, and review what the agent proposes after it reads external pages. Toggle it off in Customize to keep the config but stop it from loading, or delete the agentsearch block from mcp.json to remove it. Add the agentsearch block to ~/.cursor/mcp.json , make sure it's on in Customize, and ask Cursor's agent about something that changed last week. When you need full pages, add a capped wallet key for Extract https://agentsearchhq.com/extract?utm source=devto&utm medium=referral&utm campaign=add-web-search-to-cursor-mcp and Render https://agentsearchhq.com/render?utm source=devto&utm medium=referral&utm campaign=add-web-search-to-cursor-mcp . Check pricing https://agentsearchhq.com/pricing?utm source=devto&utm medium=referral&utm campaign=add-web-search-to-cursor-mcp and the MCP setup page https://agentsearchhq.com/mcp?utm source=devto&utm medium=referral&utm campaign=add-web-search-to-cursor-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-cursor-mcp . Originally published on the AgentSearch blog https://agentsearchhq.com/blog/add-web-search-to-cursor-mcp?utm source=devto&utm medium=referral&utm campaign=add-web-search-to-cursor-mcp .