---
title: Web search and MCP
description: Give agents web search over backends you choose, with the search keys kept on the server, through POST /v1/search or as an MCP server for other tools.
section: orchestrator
order: 110
audience: [operator, builder, agent]
sources: [services/go-orchestrator/internal/config/search.go, docs/architecture.md, services/go-orchestrator/AGENTS.md, deploy/searxng]
features: [orchestrator.config-search, orchestrator.api-search]
---

`POST /v1/search` runs a web search over the backends in `search:` and returns normalised, deduplicated results. Clients never hold a search key. The venom CLI's `web_search` tool calls it first, and `/mcp` serves the same search to Claude Code, Cursor, Zed and other MCP clients.

## Minimal example {#example}

With no `search:` section the only backend is DuckDuckGo's HTML endpoint (no key, bot checks). A local SearxNG is the sovereign choice; from a checkout, `make up SERVICES="orchestrator searxng"` runs one and sets `SEARXNG_URL`.

```bash
curl -s http://127.0.0.1:8787/v1/search -H "Authorization: Bearer $VENOM_API_KEY" -H "Content-Type: application/json" \
  -d '{"query":"go 1.24 release notes","count":5,"time_range":"month"}'
```

```json
{"object": "search.result", "query": "go 1.24 release notes", "model": "venom-search", "backend": "searxng",
 "results": [{"title": "Go 1.24 Release Notes", "url": "https://go.dev/doc/go1.24", "snippet": "…", "source": "searxng"}],
 "attempts": [{"target": "searxng", "reason": "", "results": 5, "ms": 412}],
 "usage": {"calls": 1, "tokens_in": 0, "tokens_out": 0}, "cost_usd": 0}
```

## Request {#request}

| Field | Default | What it does |
|---|---|---|
| `query` | required | At most 1000 bytes. |
| `model` | `venom-search` | The search alias, or one target's `name` to force that backend. |
| `count` | 8 | 1 to 10. |
| `time_range` | none | `day`, `week`, `month`, `year`. |
| `allowed_domains`, `blocked_domains` | none | Host filters. |
| `language` | none | Passed to backends that take one. |
| `answer` | false | Try the backends that write a grounded answer first (`openai`, `dashscope`, `tavily`); the answer comes back in `answer` with `citations`. |

Targets are tried in order. One without its key, base URL or upstream is skipped with no request; one that fails or finds nothing hands over (`reason`: `5xx`, `429`, `auth`, `timeout`, `bot_check`, `error`, `empty`, `breaker_open` after 3 failures in a row, for 60 s). One with fewer than `merge_below` results is merged with the next one's. Results are deduplicated by canonical URL and near-duplicate snippets, tracking parameters are removed, and titles and snippets are cleaned, so the same backend answer is always the same bytes.

A key's `allowed_models` must include `venom-search` (or the forced target). Budgets pre-charge the costliest target's fee; the request log records the leading target and every attempt. Headers: `x-venom-upstream`, `x-venom-model` (the target), `x-venom-fallback`. Errors: `400 invalid_search_request`, `403 model_not_allowed`, `404 model_not_found` (unknown target), `429 budget_exceeded`, `502 search_failed` (every target failed), `503 no_upstream` (none enabled, with why).

`GET /v1/search/backends` lists the targets with `name`, `backend`, `enabled`, `reason`, `call_usd`, `answer` and `model` (no keys, no addresses).

## Configuration {#config}

```yaml
search:
  alias: venom-search
  timeout: 15s
  budget: 40s
  merge_below: 4
  targets:
    - {backend: searxng, base_url: "${SEARXNG_URL:-}"}
    - {backend: brave, api_key_env: BRAVE_API_KEY}
    - {backend: tavily, api_key_env: TAVILY_API_KEY}
    - {backend: duckduckgo}
    - {backend: openai, upstream: openai, model: gpt-5.4-mini}
```

| Key | Default | What it does |
|---|---|---|
| `search.alias` | `venom-search` | The name clients send as `model`. |
| `search.timeout` | `15s` | One backend attempt. |
| `search.budget` | `40s` | The whole request, all attempts. |
| `search.merge_below` | `4` | A backend with fewer results is merged with the next; negative turns merging off. |
| `search.targets` | DuckDuckGo only | The backends, in order. |
| `search.targets[].backend` | required | `searxng`, `brave`, `tavily`, `exa`, `duckduckgo`, `openai`, `dashscope`, `zai`. |
| `search.targets[].name` | the backend | Label in the log and `x-venom-upstream`, and what `model` forces. |
| `search.targets[].base_url` | none | For `searxng` (and self-hosted variants). |
| `search.targets[].api_key_env` | none | For `brave`, `tavily`, `exa`. |
| `search.targets[].upstream` | none | For `openai`, `dashscope`, `zai`: the upstream of that kind whose base URL and key are used, so a key never lives twice in the file. |
| `search.targets[].model` | none | The chat model a grounded backend runs (`openai`, `dashscope`); for `zai` the engine (default `search_pro`). |
| `search.targets[].call_usd` | the backend's list price | Per-call fee on top of tokens; a target on a local base URL costs 0. |

| Backend | Needs | Per call (list price, 2026-10-11) | Answer |
|---|---|---|---|
| `searxng` | `base_url` | $0 (self-hosted; queries go to public engines) | no |
| `brave`, `tavily`, `exa` | `api_key_env` | $0.005, $0.008, $0.005–0.007 | tavily |
| `duckduckgo` | nothing | $0 | no |
| `openai` | a kind `openai` upstream, `model` | $0.01 per search plus tokens | yes, with citations |
| `dashscope` | a kind `dashscope` upstream, `model` | tokens plus a search fee | yes |
| `zai` | a kind `zai` upstream | $0.01 | no |

## MCP server {#mcp}

`/mcp` is the same search as an MCP server (Streamable HTTP with JSON responses; `GET` answers `405`; protocol versions 2025-11-25, 2025-06-18, 2025-03-26), with client-key auth as on `/v1`. Tools: `web_search` (`query`, `count`, `answer`, `fetch` for the text of the top 0–3 pages, `time_range`, `allowed_domains`, `blocked_domains`) and `fetch_page` (`url`, `max_chars` up to 40,000: a public page as text). Page fetches refuse loopback, private, link-local and other non-public addresses after DNS and redirects, credentials in URLs and non-text types.

Claude Code's `.mcp.json`:

```json
{
  "mcpServers": {
    "venom-search": {
      "type": "http",
      "url": "http://localhost:8787/mcp",
      "headers": { "Authorization": "Bearer ${VENOM_API_KEY}" }
    }
  }
}
```

## Related

- [Environment variables](/docs/orchestrator/environment.md#providers) for `SEARXNG_URL` and the search keys, [Keys, budgets and limits](/docs/orchestrator/keys-and-budgets.md).
