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, 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.
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 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 per-call payments are new to you, read x402 pay-per-call APIs for AI agents 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 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.
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.
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.
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 , 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 and Render. Check pricing and the MCP setup page for details, or browse more guides on the AgentSearch blog.
Originally published on the AgentSearch blog.