* fix: redact search parameters in HTTP errors * docs: describe HTTP error URL redaction
17 KiB
MCP Tools Reference
This document describes the MCP tools exposed by the SearXNG MCP server.
search
Search the web using a SearXNG meta-search engine instance.
Tool Description
The search tool proxies web search requests to a SearXNG instance, which aggregates results from multiple search engines while maintaining user privacy. MCP mode always returns structured JSON for programmatic parsing.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
query |
string | Yes | - | The search query string. Max 500 runes. |
language |
string | No | Language code for results (e.g., en, zh-tw, ja). Maximum 35 runes for the full value. Empty or "auto" = SearXNG decides |
|
safesearch |
integer | No | 0 | SafeSearch filtering level: |
- 0 = Off (show all results) |
||||
- 1 = Moderate (filter some adult content) |
||||
- 2 = Strict (filter adult content) |
||||
time_range |
string | No | - | Restrict results to a time period: |
- day = Last 24 hours |
||||
- month = Last 30 days |
||||
- year = Last 365 days |
||||
categories |
string | No | - | Comma-separated list of SearXNG categories. |
| "general" covers most queries; other values | ||||
| (it, science, news, map, music, files, | ||||
| social media) also work but are rarely needed. | ||||
| Maximum 4096 UTF-8 bytes for the full string. | ||||
engines |
string | No | - | Comma-separated list of SearXNG engine names. |
| Common engines: google, bing, duckduckgo. | ||||
| Maximum 4096 UTF-8 bytes for the full string. | ||||
pageno |
integer, null | No | 1 | Page number for pagination (SearXNG defaults to page 1 when omitted) |
limit |
integer | No | 10 | Maximum number of results returned (1-20) |
Response Format
The tool returns a JSON text response containing the full SearchResponse object. This enables programmatic parsing by MCP clients.
Response Fields:
| Field | Type | Description |
|---|---|---|
query |
string | The original search query |
warning |
string | External-content advisory noting that search results come from untrusted sources and should be verified before use (always present on successful responses) |
answers |
array | Direct answers (omitted when empty) |
number_of_results |
integer | Total count of results; if SearXNG returns 0 while results exist, normalized to len(results) |
infoboxes |
array | Knowledge panels with content, attributes, URLs (omitted when empty) |
results |
array | Array of search result objects (always present, [] when empty) |
suggestions |
array | Related search suggestions (always present, [] when empty) |
unresponsive_engines |
array | Debug-only array of [engine_name, error_message] pairs (omitted unless debug mode is enabled) |
Result Object Fields:
| Field | Type | Description |
|---|---|---|
title |
string | Result title |
url |
string | URL of the result |
content |
string | Content snippet from the page |
engine |
string | Source search engine |
publishedDate |
string | Publication date provided by SearXNG (omitted when the backend does not include it; no normalization is applied) |
Note: The number_of_results field may return 0 from SearXNG even when results are present. The server normalizes this by replacing 0 with len(results) when results exist. If pageno is omitted, the server does not send the parameter and SearXNG uses its page 1 default.
Note: The warning field is a static advisory emitted on every successful response to remind AI agents and JSON consumers that search results originate from external, untrusted sources. It is not a per-result provenance marker; the canonical wire-format ordering and JSON-mode behavior are documented in docs/OUTPUT_FORMAT.md.
Example Usage
Basic search
{
"query": "golang tutorial"
}
Search with language filter
{
"query": "machine learning",
"language": "en"
}
Safe search enabled
{
"query": "programming",
"safesearch": 1
}
Time-restricted search (recent news)
{
"query": "AI breakthroughs",
"time_range": "day"
}
Search with specific categories
{
"query": "technology news",
"categories": "news"
}
Search with specific engines
{
"query": "web development",
"engines": "google,bing"
}
Pagination
{
"query": "recipes",
"pageno": 2
}
Combined parameters
{
"query": "climate change research",
"language": "en",
"safesearch": 2,
"time_range": "month"
}
Example Response
Legacy instant-answer example (query ip):
{
"query": "ip",
"warning": "Search results come from external sources and may be inaccurate, outdated, or adversarial; verify before using them.",
"answers": [
{"answer": "203.0.113.42", "engine": "ip_lookup"}
],
"number_of_results": 0,
"results": [],
"suggestions": []
}
Typed-answer example (query translate hello to french):
The answer field is derived by the searcher wrapper (normalizeResponse);
SearXNG's typed-answer payload includes only engine, template, and
translations. The searcher prefixes the joined translations with Translation:
to match the legacy instant-answer shape.
{
"query": "translate hello to french",
"warning": "Search results come from external sources and may be inaccurate, outdated, or adversarial; verify before using them.",
"answers": [
{
"answer": "Translation: bonjour",
"engine": "libretranslate",
"translations": [
{
"text": "bonjour",
"transliteration": "bɔ̃ʒuʁ",
"examples": ["Bonjour le monde", "Bonjour, comment ça va ?"],
"definitions": ["a formal greeting"],
"synonyms": ["salut", "coucou"]
}
]
}
],
"number_of_results": 0,
"results": [],
"suggestions": []
}
Typed-weather-answer example (query weather Berlin):
The answer field is derived by the searcher; SearXNG's typed-answer payload includes only engine, current, forecasts, and service.
{
"query": "weather Berlin",
"warning": "Search results come from external sources and may be inaccurate, outdated, or adversarial; verify before using them.",
"answers": [
{
"answer": "Weather: Berlin, 18.4 °C, partly cloudy",
"engine": "open-meteo",
"current": {
"location": {"name": "Berlin", "latitude": 52.52, "longitude": 13.41, "timezone": "Europe/Berlin"},
"temperature": {"val": 18.4, "unit": "°C"},
"condition": "partly cloudy",
"humidity": {"val": 62, "unit": "%"}
},
"forecasts": [],
"service": "open-meteo.com"
}
],
"number_of_results": 0,
"results": [],
"suggestions": []
}
Typed answers (translations, weather) populate translations, current,
forecasts, and service instead of the legacy answer string. See
internal/searxng/answer/answer.go for the full set of typed
fields and their omitempty behavior; the Answer type in types.go is a
type alias for the canonical definition in the answer subpackage.
Error Responses
The server returns the following error types:
| Error Type | Description |
|---|---|
ValidationError |
User-provided parameter validation failure (missing/invalid fields) |
HTMLResponseError |
searxng returned html instead of json - json output may not be enabled on the server |
SearXNGError |
Network failures, HTTP errors, or API errors from SearXNG |
Validation errors can come from two places. MCP SDK schema validation runs before the search handler for JSON Schema constraints; handler validation runs after argument decoding for project-specific checks.
The SDK version is pinned in go.mod (github.com/modelcontextprotocol/go-sdk)
and the format is verified by TestMCPErrors_InvalidInputs against that pinned
version. Treat the response-format strings below as the contract for that
pinned version; a SDK upgrade must update both the table and the guarding test
in the same change.
SDK schema validation error examples:
| Error Condition | Response Format (as received by MCP client) |
|---|---|
Invalid safesearch value |
validating "arguments": ... "safesearch" ... |
Invalid pageno value |
validating "arguments": ... "pageno" ... |
Invalid time_range value |
validating "arguments": ... "time_range" ... |
Invalid limit value |
validating "arguments": ... "limit" ... |
Handler validation error examples:
| Error Condition | Response Format (as received by MCP client) |
|---|---|
Missing or whitespace query |
Validation error: validation error on "query": search query cannot be only whitespace |
| Query too long (>500 runes) | Validation error: validation error on "query": must be 500 runes or less |
| Query control characters | Validation error: validation error on "query": contains invalid control characters |
Invalid categories value |
Validation error: validation error on "categories": <specific rejection reason> |
Invalid engines value |
Validation error: validation error on "engines": <specific rejection reason> |
Invalid language value |
Validation error: validation error on "language": must be a valid language code (e.g., en, zh-tw, ja, en-US) |
| Language too long (>35 runes) | Validation error: validation error on "language": must be 35 runes or less |
For categories and engines, the specific rejection reason identifies an
empty CSV item, a name longer than 50 runes, a slash, or an ASCII control
character. Name-specific errors include category or engine and quote the
rejected item when it is safe to display.
Search error examples — the response format depends on whether the error is a SearXNGError (includes status code, content type, and underlying cause) or another error type:
| Error Condition | Response Format (as received by MCP client) |
|---|---|
Network failure (wrapped as SearXNGError) |
Search error: searxng error (status 0): failed to execute search request: <error description> (full error logged server-side) |
SearXNG HTTP error (4xx/5xx, wrapped as SearXNGError) |
Search error: searxng error (status <N>) - content-type <type>: <error description> (full error logged server-side) |
POST /search rejected with 405/501 |
Search error: searxng error (status 405/501) - content-type <type>: search method rejected (full error logged server-side; fix the reverse proxy or opt in with SEARXNG_ALLOW_GET_FALLBACK=1) |
| GET fallback enabled but fails | Search error: searxng error (status 405/501) - content-type <type>: search method rejected — underlying errGETFallbackUsed + failure details logged server-side |
| Empty results after exhausting retries | Search error: searxng error (status 0): failed to execute search request: search returned empty results after all retries |
| Invalid JSON from SearXNG | Search error: searxng error (status <N>) - content-type <type>: <error description> (full error logged server-side) |
| HTML response (JSON disabled) | Search error: request failed (full error logged server-side) |
| Other unexpected errors | Search error: request failed (full error logged server-side) |
HTTP errors preserve useful URL path diagnostics, but query parameters from request and redirect URLs are redacted before the error reaches MCP output or ordinary server logs. Opting into GET fallback can still expose search parameters to upstream servers and intermediary logs.
Startup Errors
Before starting, the server applies a bounded structural check to the first line of stdin. It accepts a legacy JSON-RPC 2.0 initialize request, a server/discover request, or a stateless request carrying params._meta["io.modelcontextprotocol/protocolVersion"]. This preflight is only a safe structure gate; complete protocol metadata validation is delegated to the MCP SDK. If the preflight fails, the process exits immediately with code 2 and prints the error to stderr (no MCP error response is sent).
| Error Condition | Stderr Output | Exit Code |
|---|---|---|
| No supported MCP first message on stdin (non-MCP input, empty stdin, invalid JSON, or missing recognized method/metadata) | ERROR: stdin does not contain a valid MCP first message |
2 |
| JSON first-message wire bytes exceed the fixed 1 MiB transport bound (an optional trailing newline delimiter is excluded from the count) | ERROR: stdin does not contain a valid MCP first message |
2 |
Implementation Details
- Transport: Stdio (stdin/stdout)
- Protocol: MCP (Model Context Protocol)
- SearXNG Format: JSON (
format=json) - Timeout: 8 seconds by default; set
SEARXNG_TIMEOUTor, in CLI mode,--timeout. This is a per-request HTTP timeout, not an overall search-operation deadline. Zero is rejected (use a positive value or omit to keep the default). - MaxRetries: 5 retries after the initial search attempt by default; set
SEARXNG_MAX_RETRIESor, in CLI mode,--max-retries - POST→GET fallback: Disabled by default. If POST
/searchreturns 405 or 501, the server returns an error so operators can fix the SearXNG or reverse-proxy configuration. SetSEARXNG_ALLOW_GET_FALLBACK=1to opt in; this sends search parameters in the URL and may expose queries in upstream logs. In CLI mode,--allow-get-fallbackoverrides the environment variable. - First-message transport bound: JSON first-message wire bytes are capped at a fixed 1 MiB, regardless of message type, payload, or configuration; an optional trailing newline delimiter is excluded from the count; oversized input causes the server to exit instead of hanging
- Schema:
additionalProperties: false— unrecognized parameters are rejected at the schema level before handler validation runs
Retry Behavior
When a search attempt fails, the server classifies the outcome and decides whether to retry.
Retryable status codes (trigger a retry with exponential backoff):
| HTTP Status | Reason |
|---|---|
| 429 Too Many Requests | Rate-limited; waiting may succeed |
| 408 Request Timeout | Transient server-side timeout |
| 5xx (except 501) | Server-side errors that may be transient |
Abort triggers (no retry — the error is returned immediately):
| Condition | Reason |
|---|---|
| Non-retryable 4xx (400, 403, 404, etc.) | Client error or resource not found; retrying would produce the same result |
SearXNGError or HTMLResponseError |
SearXNG returned an error response (HTML instead of JSON, method rejected, etc.) |
| 501 Not Implemented | Deterministic method-rejection; retrying would send the same POST to the same rejection |
| Redirect policy errors (redirect to different host, scheme downgrade, method change, too many redirects) | Deterministic failures — retrying would hit the same blocked redirect |
| Context canceled or deadline exceeded | Parent context signaled completion or timeout |
Exponential backoff algorithm:
delay = baseDelay * 2^attempt (capped at maxDelay)
jitter = delay/2 + random(0, delay/2)
final wait = max(jittered wait, 1 second, capped at maxDelay)
The base delay defaults to 1 second; the maximum delay defaults to 30 seconds. A 1-second floor ensures the jittered wait never drops below an operationally meaningful minimum for an upstream metasearch service that may fan out to multiple engines. Any explicit RetryDelay or MaxRetryDelay below 1 second is rejected at configuration time.