agentsearch-mcp

# agentsearch-mcp

MCP (Model Context Protocol) server for people running their own [AgentSearch](https://agentsearchhq.com/?utm_source=github&utm_medium=readme&utm_campaign=mcp)-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:

```bash
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](https://agentsearchhq.com/specs/render-openapi.json))

---

## 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

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

From a local checkout:

```bash
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):

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

Optional API key:

```json
"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`

```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

```bash
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