searxng-mcp-go/docs/MCP_TOOLS.md
XLion d6cf967473
fix: redact search parameters in HTTP errors (#577)
* fix: redact search parameters in HTTP errors

* docs: describe HTTP error URL redaction
2026-08-12 23:57:32 +08:00

17 KiB

MCP Tools Reference

This document describes the MCP tools exposed by the SearXNG MCP server.

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

{
  "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_TIMEOUT or, 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_RETRIES or, in CLI mode, --max-retries
  • POST→GET fallback: Disabled by default. If POST /search returns 405 or 501, the server returns an error so operators can fix the SearXNG or reverse-proxy configuration. Set SEARXNG_ALLOW_GET_FALLBACK=1 to opt in; this sends search parameters in the URL and may expose queries in upstream logs. In CLI mode, --allow-get-fallback overrides 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.