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.
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}" }
}
}
}Related
- Environment variables for
SEARXNG_URLand the search keys, Keys, budgets and limits.