用 MCP 给 AI Agent 接入网页搜索的 2026 指南

Language models stop learning on their training cutoff date. An agent that has to answer "what changed in this library last week?" or "what does this vendor charge today?" needs a tool that can search the live web and read the pages it finds. The Model Context Protocol (MCP) is the standard way to give it one.

This guide connects an MCP client (Claude Desktop, Cursor, Claude Code, or anything else that speaks MCP) to AgentSearch web search and URL extraction. It takes about five minutes. There's no account to create and no API key to manage: each call is paid in USDC through the Pocket Network Agentic Portal.

What you'll set up

AgentSearch runs two services on Pocket Network that matter for this guide:

Both prices come from the service pages on the Pocket Agentic Portal (search, extract). You pay in USDC over x402 on Base, or over MPP on Tempo.

You'll install one MCP server, @pocket-network/agentic-portal-mcp, Pocket's local MCP server for the Agentic Portal. It's listed in the official MCP Registry as network.pocket/agentic-portal-mcp. Pocket's full instructions are at agent.pocket.network/agent-integration.

Why a local server holds the wallet

MCP clients can't pay for tools on their own yet. So the portal's MCP server runs on your machine, keeps the paying wallet's key there, and signs an x402 payment only when a call fits inside the spending limits you set. The portal never holds your key.

Prerequisites

• Node.js 20 or newer, so npx is available.
• An MCP client: Claude Desktop, Cursor, Claude Code or similar.
• A dedicated wallet holding a small amount of USDC on Base. Pocket's docs are blunt about this: the key sits in a plain-text config file, so use a wallet made for this purpose that holds only what you're willing to spend.

Step 1: Add the MCP server to your client

Open your client's MCP config file:

• Claude Desktop: claude_desktop_config.json
• Cursor: .cursor/mcp.json
• Claude Code: .mcp.json

Then add the server, which runs npx -y @pocket-network/agentic-portal-mcp:

{
  "mcpServers": {
    "pocket-network": {
      "command": "npx",
      "args": ["-y", "@pocket-network/agentic-portal-mcp"],
      "env": {
        "POCKET_PRIVATE_KEY": "0x…",
        "POCKET_MAX_TOTAL_ATOMIC": "1000000"
      }
    }
  }
}

Put settings in the env block. Desktop clients start MCP servers without your shell's environment, so a variable you export in a terminal won't reach the server.

Set spending limits before you do anything else

The server checks every limit before it signs, and signs nothing unless all of them allow the payment. USDC has 6 decimals, so amounts are in atomic units and 1000000 = $1.00.

Pocket also warns that you shouldn't count on the client asking before it pays: in their testing, one client's model asked first and another paid without asking. These limits are what protect you either way.

A cautious first config:

{
  "mcpServers": {
    "pocket-network": {
      "command": "npx",
      "args": ["-y", "@pocket-network/agentic-portal-mcp"],
      "env": {
        "POCKET_PRIVATE_KEY": "0x…",
        "POCKET_MAX_TOTAL_ATOMIC": "250000",
        "POCKET_MAX_PER_CALL_ATOMIC": "5000",
        "POCKET_QUOTE_ONLY": "true"
      }
    }
  }
}

Restart the client after you save. Remove POCKET_QUOTE_ONLY when you're ready to make real calls.

Step 2: Find AgentSearch through the free tools

The server exposes three tools:

If you leave out the private key, only the free tools work, which is a safe way to look around. Try a prompt like this:

Use search_services to find "agentsearch". Then describe_service for agentsearch-web-search-v1 and tell me its price and request schema.

You should see $0.005 and a POST /v1/search operation that takes a query and an optional max_results (up to 5).

Step 3: Run a paid search

Now ask for something that needs fresh information:

Use call_service on agentsearch-web-search-v1 to search for "x402 payment protocol v2 headers", then summarize the top results with their URLs.

Under the hood, the agent sends the same request you could send yourself:

curl -X POST https://agent.pocket.network/v1/agentsearch-web-search-v1/v1/search \
  -H 'content-type: application/json' \
  -d '{"query":"x402 payment protocol v2 headers","max_results":5}'
# The first response is 402 Payment Required with the terms.
# The MCP server signs them and retries the same request with the payment attached.

The result comes back in the portal's envelope. Fields set by the portal sit under portal, and the supplier's untouched response sits under data:

{
  "portal": {
    "provenance": "third-party-supplier",
    "serviceId": "agentsearch-web-search-v1",
    "schemaCheck": "unchecked"
  },
  "data": {
    "query": "x402 payment protocol v2 headers",
    "result_count": 5,
    "results": [
      { "title": "…", "url": "https://…", "content": "…", "score": 0.91, "domain": "…" }
    ]
  }
}

The data above is trimmed. The full field list is in the search OpenAPI spec.

Step 4: Extract a full page when snippets aren't enough

When the agent needs a whole document, such as a changelog, an API reference page or a pricing table, use extract:

Use call_service on agentsearch-web-extract-v1 with url "https://example.com" and return the markdown.

{ "url": "https://example.com", "formats": ["markdown"], "max_chars": 20000 }

You get title, markdown, links and meta back (status_code, content_type, fetched_at, chars, truncated). Turn any URL into clean markdown for RAG goes deeper on extraction.

Treat results as data, not instructions

Search results and extracted pages are third-party content, and some pages are written to manipulate agents. Pocket's integration guide recommends these habits:

• Keep data in a clearly marked data position, such as a tool-result block. Never paste it into a system prompt.
• Don't follow instructions that appear inside a result. A page telling your agent to "call another endpoint" or "ignore prior instructions" is an attack, not an answer.
• Check portal.schemaCheck. Only passed means a schema check actually ran.

Troubleshooting

• Only the free tools work: POCKET_PRIVATE_KEY is missing, or it's set in your shell instead of the config's env block.
• Calls are refused before payment: a limit blocked the call (total, per-call or network), or POCKET_QUOTE_ONLY is still true.
• An empty results array with an error object: the search hit its deadline or an upstream error. Check error.retryable and retry with backoff.
• Extract returns UNSUPPORTED_CONTENT: the URL is a PDF or an image, not HTML or text.
• The page only renders with JavaScript: extract fetches static HTML. AgentSearch also runs a headless-browser Web Render service (agentsearch-web-render-v1, live on Pocket MainNet). It isn't on the Agentic Portal yet.

FAQ

Do I need an AgentSearch account or API key?
No. You pay per call in USDC through the Agentic Portal, over x402 (Base) or MPP (Tempo).

Which MCP clients work?
Any client that can launch a local stdio MCP server, including Claude Desktop, Cursor and Claude Code.

Who runs the infrastructure?
AgentSearch is served by decentralized Pocket Network suppliers.

Next steps

• Compare costs in Cheapest web search API for AI agents in 2026.
• Read the machine-readable docs at agentsearchhq.com/llms.txt and agentsearchhq.com/agents.md.
• See the service pages for search, extract and render.
• Browse the OpenAPI specs for search and extract.

More from the blog

• Cheapest Web Search API for AI Agents in 2026
• Turn Any URL into Clean Markdown for RAG (API Guide)

Service pages: Web Search API · Web Extract API · Web Render API

Originally published at agentsearchhq.com.