Skip to content
Docs menu

Web search and MCP

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.

View .md

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

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.

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

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

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

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