Agentsearch MCP Server

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

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

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