{"slug": "how-to-add-free-web-search-to-cursor-with-mcp-no-api-key", "title": "How to Add Free Web Search to Cursor with MCP (No API Key)", "summary": "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.", "body_md": "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.\n\nWe'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:\n\nFree tier: up to 25 searches/day per IP, no key needed (shared daily capacity; paid calls have no cap).\n\n**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.\n\nUsing 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).\n\n`npx` on your PATH (`node -v`). Cursor starts the server with Cursor reads MCP servers from two files:\n\n| File | Scope | Good for | \n|---|---|---|\n| `~/.cursor/mcp.json` | Global: every project on your machine | Tools you want everywhere, and anything with a secret | \n| `.cursor/mcp.json` in the project root | Project: this repo only | Tools you want to share with the team through git | \n\nFor web search you usually want it everywhere, so create or open `~/.cursor/mcp.json` (on Windows that's `%USERPROFILE%\\.cursor\\mcp.json`) and add:\n\n```\n{\n  \"mcpServers\": {\n    \"agentsearch\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@agentsearchhq/agentsearch-mcp\"]\n    }\n  }\n}\n```\n\nIf the file already has servers, add the `\"agentsearch\"` block inside the existing `mcpServers` object.\n\n`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.\nNo `env` block is needed for free search.\n\nTo 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.\n\nTwo things we confirmed with the Cursor CLI:\n\n`not loaded (needs approval)` until we approved it with `agent mcp enable agentsearch`, so a cloned repo can't start processes without your OK.\nNever put a wallet key in a committed project file. Step 5 shows how to reference it instead.\n\nIn 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.\n\nIf you have the Cursor CLI installed, you can also check from a terminal:\n\n```\nagent mcp list\nagentsearch: ready\n```\n\nAnd to see the tools:\n\n```\nagent mcp list-tools agentsearch\nTools for agentsearch (5):\n- agentsearch_extract (url, formats, max_chars)\n- agentsearch_render (url, formats, max_chars, screenshot, screenshot_format, full_page, viewport, wait_until, wait_for_selector, wait_ms, block)\n- agentsearch_review_lookup (task, service_id, max_price_usd, network, limit, include_down)\n- agentsearch_review_submit (service_id, success, task, latency_ms, quality, price_paid_usd, note, called_at, proof_tx_hash, pocket_session_id)\n- agentsearch_web_search (query, max_results)\n```\n\nWhat the five tools do:\n\n`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.\nAccording 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:\n\n```\nSearch the web for the current stable version of Next.js and tell me whether package.json is behind.\nUse agentsearch to find the official migration guide for ESLint flat config, then list what we need to change in our .eslintrc.\n```\n\n**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.\n\nHere's a trimmed result from a real call to `agentsearch_web_search` with `max_results: 1`:\n\n```\n{\n  \"query\": \"cursor mcp\",\n  \"result_count\": 1,\n  \"results\": [\n    {\n      \"title\": \"Model Context Protocol (MCP) | Cursor Docs\",\n      \"url\": \"https://cursor.com/docs/mcp\",\n      \"content\": \"Model Context Protocol (MCP) enables Cursor to connect to external tools and data sources...\",\n      \"domain\": \"cursor.com\"\n    }\n  ]\n}\n```\n\nResults are passages, not whole pages. For full pages, use Extract and Render.\n\n[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.\n\nThe 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.\n\n**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.\n\nDon't paste the key into `mcp.json`. Cursor's config supports `${env:NAME}` interpolation in `env` values, so the file only holds a reference:\n\n```\n{\n  \"mcpServers\": {\n    \"agentsearch\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@agentsearchhq/agentsearch-mcp\"],\n      \"env\": {\n        \"AGENTSEARCH_WALLET_PRIVATE_KEY\": \"${env:AGENTSEARCH_WALLET_PRIVATE_KEY}\",\n        \"AGENTSEARCH_MAX_TOTAL_ATOMIC\": \"50000\"\n      }\n    }\n  }\n}\n```\n\nSet `AGENTSEARCH_WALLET_PRIVATE_KEY` in the environment Cursor starts from, restart Cursor, and keep this entry in your global `~/.cursor/mcp.json`.\n\n**Spend caps.** The server checks these limits before it signs anything:\n\n`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.\nWhen a cap is reached, the tool returns `Session spend cap reached ... Nothing was signed.` instead of paying.\n\nOnce 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.\n\n**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.\n\n**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`.\n\n**Windows.** If the logs show that `npx` can't be started, wrap it in `cmd /c`:\n\n```\n{\n  \"mcpServers\": {\n    \"agentsearch\": {\n      \"type\": \"stdio\",\n      \"command\": \"cmd\",\n      \"args\": [\"/c\", \"npx\", \"-y\", \"@agentsearchhq/agentsearch-mcp\"]\n    }\n  }\n}\n```\n\nIn JSON, Windows paths need doubled backslashes (`C:\\\\Program Files\\\\nodejs\\\\npx.cmd`). A single backslash makes the whole file invalid.\n\n**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.\n\n**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.\n\n**Extract or Render says \"paid tool ... No wallet is configured\".** That's expected without a key. No call was made and nothing was charged.\n\n**Search returns \"AGENTSEARCH_MODE must be one of 'free', 'paid' or 'auto'\".** Fix the typo in `env` or remove the variable.\n\n**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.\n\nFor 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).\n\n`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`.\nMore 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).\n\nNo. 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).\n\nUse 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.\n\nNot 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.\n\nUp to 5 per call. The agent can ask for fewer with `max_results` (1 to 5).\n\nYes. The CLI uses the same MCP configuration as the editor, and we tested these configs with `agent mcp list`.\n\nTreat 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.\n\nToggle it off in Customize to keep the config but stop it from loading, or delete the `agentsearch` block from `mcp.json` to remove it.\n\nAdd 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).\n\n*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).*", "url": "https://wpnews.pro/news/how-to-add-free-web-search-to-cursor-with-mcp-no-api-key", "canonical_source": "https://dev.to/agentsearchhq/how-to-add-free-web-search-to-cursor-with-mcp-no-api-key-5521", "published_at": "2026-10-26 15:05:12+00:00", "updated_at": "2026-10-26 15:14:45.103454+00:00", "lang": "en", "topics": ["ai-tools", "ai-agents", "agent-protocols", "developer-tools"], "entities": ["Cursor", "AgentSearch", "@agentsearchhq/agentsearch-mcp", "npm", "Model Context Protocol", "Node.js", "Claude Code"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/how-to-add-free-web-search-to-cursor-with-mcp-no-api-key", "markdown": "https://wpnews.pro/news/how-to-add-free-web-search-to-cursor-with-mcp-no-api-key.md", "text": "https://wpnews.pro/news/how-to-add-free-web-search-to-cursor-with-mcp-no-api-key.txt", "jsonld": "https://wpnews.pro/news/how-to-add-free-web-search-to-cursor-with-mcp-no-api-key.jsonld"}}