Add Web Search to Your AI Agent with MCP (2026 Guide)

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}'

{
  "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://...",
        "snippet": "...",
        "score": 0.91,
        "domain": "...",
        "date": "..."
      }
    ]
  }
}

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

To integrate live web search and content extraction into your AI agent workflows, you must deploy the @pocket-network/agentic-portal-mcp server. This server facilitates payments for Pocket Network services by signing x402 requests locally, ensuring your private key is never transmitted to the service provider.

Installation requires Node.js 20 or newer to support the npx execution model. Because MCP clients, such as Claude Desktop, Cursor, or Claude Code, launch the server in an isolated process, you must define all configuration parameters, including the wallet's private key, within the client's configuration file rather than your shell environment.

Configuring Spending Limits

Security is managed through hard-coded limits in the MCP configuration. Because USDC utilizes 6 decimal places, spending limits are defined in atomic units (e.g., 1,000,000 units equals $1.00 USDC). Configure the following environment variables within your mcpServers definition:

• POCKET_PRIVATE_KEY: The private key of a dedicated wallet containing USDC on Base. Use a wallet specifically for this integration to mitigate risk.
• POCKET_MAX_TOTAL_ATOMIC: The cumulative spend limit for the server session.
• POCKET_MAX_PER_CALL_ATOMIC: The maximum cost permitted for a single tool invocation. Set this to 5000 (0.005 USDC) to prevent overspending on individual operations.
• POCKET_QUOTE_ONLY: Set to true to test service discovery and pricing without executing payments.

Example implementation for an MCP configuration file:

{
  "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"
      }
    }
  }
}

After updating your configuration, restart the client. Use search_services to explore available tools without cost, and once validated, remove POCKET_QUOTE_ONLY to enable live execution. When processing results, strictly treat them as external data; do not inject them into system prompts or follow instructions embedded within the retrieved content to prevent prompt injection attacks.

Before an agent can invoke a live web search or page extraction, it must locate the correct AgentSearch service definitions. The Agentic Portal exposes three MCP tools; the first two are free and can be used without a private key:

• search_services – queries the portal catalogue by keyword or category.
• describe_service – returns the price, HTTP method, endpoint path, request schema, and a captured example for a given service ID.

A typical discovery flow looks like this:

search_services("agentsearch")
describe_service("agentsearch-web-search-v1")
describe_service("agentsearch-web-extract-v1")

The describe_service output shows that both agentsearch-web-search-v1 and agentsearch-web-extract-v1 cost $0.005 per call and accept a JSON payload defined in their OpenAPI specs.

Running a paid search

Once the service IDs are known, the agent issues a call_service request. The underlying HTTP call can be reproduced with curl:

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 MCP server first receives a 402 Payment Required response containing the seller’s terms. It signs an x402 payment (using the wallet configured in POCKET_PRIVATE_KEY) and retries automatically. The final envelope returned by the portal has two top‑level objects:

{
  "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": "..."
      }
    ]
  }
}

Extracting a full page

If the snippets returned by the search are insufficient, the agent can request a clean markdown extraction:

curl -X POST https://agent.pocket.network/v1/agentsearch-web-extract-v1/v1/extract \
  -H "Content-Type: application/json" \
  -d '{
        "url":"https://example.com",
        "formats":["markdown"],
        "max_chars":20000
      }'

The response follows the same envelope pattern, with data.title, data.markdown, data.links, and metadata fields such as status_code, content_type, and fetched_at. These fields should be treated as raw data; they must never be injected into system prompts or executed as instructions, as third‑party pages can contain malicious directives.

Operational safeguards

• Set POCKET_MAX_TOTAL_ATOMIC and POCKET_MAX_PER_CALL_ATOMIC to enforce spending limits (e.g., 1 000 000 atomic units ≈ $1.00).
• Use POCKET_QUOTE_ONLY=true for dry‑run discovery; remove it before real calls.
• Validate portal.schemaCheck – a value of unchecked means no schema validation was performed.

Following this pattern lets enterprise engineers integrate live web search and extraction into Retrieval‑Augmented Generation pipelines while keeping payment handling, data hygiene, and security controls explicit.

When an LLM agent consumes data from agentsearch-web-search-v1 or agentsearch-web-extract-v1, the response is wrapped in a portal envelope that contains metadata such as schemaCheck. A passed value indicates that the service performed a schema validation; unchecked means no validation occurred, and the payload must be treated as untrusted raw data.

Best‑practice checklist for third‑party data

• Isolate data from prompts. Store the entire result in a dedicated data block (e.g., a JSON field or a tool‑result variable) and never concatenate it into a system or user prompt.
• Validate schema. Verify portal.schemaCheck === "passed" before deserializing. If the check is unchecked, run a local JSON schema validator against the expected contract.
• Guard against instruction injection. Do not execute instructions that appear inside the payload (e.g., “call another endpoint” or “ignore prior instructions”). Treat any such text as plain data.
• Apply least‑privilege limits. Configure MCP environment variables (POCKET_MAX_TOTAL_ATOMIC, POCKET_MAX_PER_CALL_ATOMIC) to cap spending and prevent runaway calls.
• Follow compliance frameworks. Align the handling of third‑party data with standards such as NIST SP 800‑53 for data integrity, and ensure audit logs satisfy ISO 27001 requirements for access control.

Common error scenarios

• Missing private key. Free tools work, but paid calls fail with “POCKET_PRIVATE_KEY is missing.” Add the key to the MCP server’s env block, not just the shell.
• Limit blocks. Calls are rejected when POCKET_MAX_TOTAL_ATOMIC or POCKET_MAX_PER_CALL_ATOMIC is exceeded, or when POCKET_QUOTE_ONLY remains true.
• Empty result with error.retryable. Indicates a timeout or upstream failure; implement exponential back‑off and retry.
• Unsupported content. UNSUPPORTED_CONTENT is returned for PDFs, images, or JavaScript‑rendered pages. Use the agentsearch-web-render-v1 service for headless‑browser rendering.

Next steps and resources

• Compare per‑call costs in the Cheapest Web Search API cost analysis.
• Review the machine‑readable OpenAPI specifications:
  • Search API spec
  • Extract API spec
• Read the detailed integration guide on handling portal.schemaCheck and instruction injection at AgentSearch Integration Guide.
• Explore further security hardening patterns in the OWASP Top Ten for injection attacks.