AgentSearch (agentsearchhq.com)

agentsearch-mcp

MCP (Model Context Protocol) server for people running their own AgentSearch-compatible backend. It exposes web search, page extract, and JavaScript page rendering (headless browser) to Cursor, Claude Desktop, and other MCP hosts over stdio.

AGENTSEARCH_BASE_URL is required and points at that API. There is no built-in default host.

For pay-per-call access with no backend of your own, use Pocket's official MCP server instead:

npx -y @pocket-network/agentic-portal-mcp

That server calls agentsearch-web-search-v1 and agentsearch-web-extract-v1 at $0.005/call over x402. Details: https://agentsearchhq.com/?utm_source=github&utm_medium=readme&utm_campaign=mcp

This package calls your API directly:

• Search: POST {AGENTSEARCH_BASE_URL}/v1/search with body { "query": "...", "max_results": 5 }
• Extract: POST {AGENTSEARCH_BASE_URL}/v1/extract
• Render: POST {AGENTSEARCH_BASE_URL}/v1/render (headless Chromium; OpenAPI spec)

---

Tools

Tool	Args	Description
agentsearch_web_search	query (string, required), max_results (number, optional, default 5, clamped 1–5)	Web search. Returns pretty-printed JSON. Use for a query; use extract when you already have a URL. Read-only HTTP.
agentsearch_extract	url (absolute URL, required), formats (string[], optional), max_chars (positive integer, optional)	Page extract via POST /v1/extract. Use when you already have a URL. Read-only HTTP.
agentsearch_render	url (absolute http(s) URL, required); optional: formats (markdown|text|html|links, default ["markdown"]), max_chars (1–100000), screenshot, screenshot_format (png|jpeg), full_page, viewport ({width 320–1920, height 240–1600}), wait_until (domcontentloaded|load|networkidle), wait_for_selector, wait_ms (0–1500), block (image|media|font|stylesheet)	Renders a JavaScript-heavy page in headless Chromium via POST /v1/render and returns title, status, meta, and the rendered markdown/text/HTML/links (plus optional base64 screenshot). Use when extract returns empty/partial content for an SPA; prefer extract for static pages. Read-only HTTP.

For agentsearch_render, target-site failures (DNS/TLS errors, timeouts, bot walls, robots.txt) come back as a normal result whose JSON has a non-null error object (code, message, retryable); bad input (400), oversize body (413), rate limits (429) and backend faults (500) are MCP errors. The backend enforces a ~4.2 s render deadline.

---

Requirements

• Node.js 20+
• Your own AgentSearch-compatible API. Set AGENTSEARCH_BASE_URL to its base URL. The process exits at startup if that variable is missing.

---

Install

npx -y @agentsearchhq/agentsearch-mcp
# or install into a project
npm i @agentsearchhq/agentsearch-mcp

From a local checkout:

cd agentsearch-mcp
npm install
npm run build

Scripts: build → tsc, start → node dist/index.js, test → build + node --test test/*.mjs, prepare → runs build.

Binary: agentsearch-mcp → dist/index.js

---

Environment variables

Variable	Required	Notes
AGENTSEARCH_BASE_URL	yes	Base URL of your API (no trailing slash). No default.
AGENTSEARCH_API_KEY	no	Optional Authorization: Bearer …. On 401 the client retries once without the key.

See .env.example. Never commit a real .env.

---

Cursor

Project (.cursor/mcp.json) or user (~/.cursor/mcp.json / Cursor Settings → MCP):

{
  "mcpServers": {
    "agentsearch": {
      "command": "npx",
      "args": ["-y", "@agentsearchhq/agentsearch-mcp"],
      "env": {
        "AGENTSEARCH_BASE_URL": "https://your-agentsearch-host.example"
      }
    }
  }
}

Optional API key:

"env": {
  "AGENTSEARCH_BASE_URL": "https://your-agentsearch-host.example",
  "AGENTSEARCH_API_KEY": "your-key-here"
}

---

Claude Desktop

Edit Claude Desktop config (claude_desktop_config.json):

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "agentsearch": {
      "command": "npx",
      "args": ["-y", "@agentsearchhq/agentsearch-mcp"],
      "env": {
        "AGENTSEARCH_BASE_URL": "https://your-agentsearch-host.example"
      }
    }
  }
}

Restart Claude Desktop after saving.

---

Local run

npm run build
AGENTSEARCH_BASE_URL=https://your-agentsearch-host.example node dist/index.js
# process waits on stdin — Ctrl+C to stop

If AGENTSEARCH_BASE_URL is unset, the process prints an error and exits.

---

License

MIT