mcp-searxng-relay

Who this is for.Teams running AI agents in corporate or government environments where outbound search is restricted, monitored, or both — and where "we use a hosted search API" is not an acceptable answer. The project prioritizes a defensible security posture and a clean audit trail over breadth of features.

This MCP server supports both thestdiotransport (for local use with Claude Desktop and similar clients) and theStreamable HTTPtransport (for networked or containerised deployments).

- A running SearXNG instance with the JSON output format enabled
- Go 1.26+ (for building from source) or Docker

Add the following to your SearXNGsettings.yml:

docker run -d \ -e SEARXNG_URL=https://your-searxng-instance.example.com \ -e MCP_PORT=8080 \ -e MCP_AUTH_TOKEN=$(openssl rand -hex 32) \ -p 8080:8080 \ ghcr.io/littleoffice/mcp-searxng-relay:latest

services: mcp-searxng: image: ghcr.io/littleoffice/mcp-searxng-relay:latest restart: unless-stopped environment: SEARXNG_URL: https://your-searxng-instance.example.com MCP_PORT: "8080" MCP_AUTH_TOKEN: your-strong-random-token ports: - "8080:8080"

Compute the two reproducibility inputs once, then choose your build tool:

SOURCE_DATE_EPOCH="$(git log -1 --pretty=%ct HEAD)" SERVER_VERSION="$(git describe --tags --always)"

docker buildx build \ --build-arg SERVER_VERSION="${SERVER_VERSION}" \ --build-arg SOURCE_DATE_EPOCH="${SOURCE_DATE_EPOCH}" \ --output type=docker,rewrite-timestamp=true \ -t mcp-searxng-relay:"${SERVER_VERSION}" .

podman build \ --build-arg SERVER_VERSION="${SERVER_VERSION}" \ --build-arg SOURCE_DATE_EPOCH="${SOURCE_DATE_EPOCH}" \ --timestamp "${SOURCE_DATE_EPOCH}" \ -t mcp-searxng-relay:"${SERVER_VERSION}" .

The multi-stage build compiles the binary on a digest-pinnedgolang:1.26.6-trixiebuilder and copies only the static binary and CA certificates into ascratchruntime image.

Note that Docker and Podman use slightly different on-disk manifest encodings, so images built with one and saved through the other will not have matching SHA-256s even when functionally identical. Pick a build tool and stick with it for cross-machine reproducibility checks.

All configuration is via environment variables. The server will refuse to start ifSEARXNG_URLis not set. At least one ofMCP_AUTH_TOKEN/MCP_AUTH_TOKENS/MCP_AUTH_TOKEN_FILEis required whenMCP_PORTis set.

¹ HTTP mode requiresat least oneof the three auth-token variables. They can also be combined: later sources override earlier ones if the same digest appears in more than one. All tokens are independently validated against a 32-character minimum.

When usingMCP_AUTH_TOKEN_FILE, each non-comment line isidentity:token. The split is on the first:, so tokens may contain colons; identities may not. Identities are arbitrary strings used only for log correlation — typically a username, agent name, or service account label.

# This is a comment. alice:7f3a8c2e9b1d4f6a0c8e2b9d4f6a0c8e2b9d4f6a0c8e2b9d4f6a0c8e2b9d4f6a bob:0e1d2c3b4a596877665544332211ffeedccbbaa998877665544332211ffeedc service-ci:9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba # Identity rotation: both lines below are accepted for "alice" until # the old one is removed. Useful for zero-downtime token rotation. alice:newtokenvaluefor32charsminimum0123456789abcdef0123456789abcdef

Set the file mode to0600and place it ontmpfs(or a Docker secret / Kubernetes projected volume) if your threat model includes other users on the host.

The MCP Streamable HTTP transport is stateful by default: the SDK assigns a session ID oninitialize, the client echoes it on every subsequent request, and the SDK looks it up in an in-memory map. When the server restarts, that map is rebuilt empty — the client's old session ID returns 404, and many MCP clients fail to re-initialize automatically despite the spec requiring it. The result is "I redeployed and my agent is stuck until I restart it."

For audit correlation in stateful mode, every tool-call log line carries bothidentity(which token authenticated the request) andsession_id(which initialize handshake the request belongs to). Thesession_idconnects tool calls back to the"session initialized"log line for the same session — that's where the client's identity is recorded at handshake time. Idle sessions are reaped afterMCP_SESSION_MAX_AGEby a background janitor (defaults to 7 days); sessions cleanly closed by the client (DELETE) are tracked too and freed immediately.

In stateless mode thesession_idfield is still present and stable across requests from one client, but the binding is weaker: the SDK uses whatever value the client sends inMcp-Session-Idwithout validating it (only generating a fresh one if the client didn't supply any). This means an authenticated client could, in principle, forge anothersession_idof its choice — which is harmless for honest clients but means you can't treatsession_idas a server-verified attribute.identityremains server-validated in both modes, and is the canonical join key when forgery-resistance matters.

If you don't want client-assertedsession_idshowing up in your logs at all, setmcp.ServerOptions.GetSessionIDtofunc() string { return "" }inserver.go:buildMCPServer. The SDK will then omit theMcp-Session-Idresponse header andreq.Session.ID()returns empty for every request — true "sessionless" mode. Not exposed as an env var because the use case is narrow.

The two janitor knobs serve different purposes and are worth understanding before changing the defaults:

-

MCP_SESSION_MAX_AGEis apolicysetting. It caps how long any one session is allowed to live. Lower it (e.g.24h) when your environment rotates auth tokens daily — sessions older than the rotation period are using a token that no longer exists in the table, so reaping them forces a clean re-handshake with the current one. Lower it further for compliance frameworks that require periodic re-authentication. Raise it (e.g.720h/ 30d) for batch or scheduled agents that legitimately go idle for long stretches.

MCP_SESSION_JANITOR_INTERVALis amechanismsetting. It controls how often the cleanup pass runs. Shorter intervals catch expired sessions sooner at the cost of a small amount of mutex contention; longer intervals are cheaper but allow more overshoot pastMCP_SESSION_MAX_AGE. The default of15mmeans a session might live up to 15 minutes past its max age before being closed — fine for the policy "approximately a week" but worth lowering if your max age is itself short.

If you don't see the session cap (mcp_active_sessionsin/metrics) climbing under load, the defaults are working and there's nothing to tune.

Execute a web search and return titles, URLs, and snippets.

{ "query": "fusion energy breakthrough", "categories": "news", "language": "en", "time_range": "month", "num_results": 5 }

Output shape.Each result is rendered as a text block of the form:

Title: Example article title URL: https://example.com/article Snippet: First sentence or two of the page… Engines: google, bing, duckduckgo

TheEnginesline is omitted when SearXNG didn't return the field (older SearXNG versions, or results from a single-engine configuration). The list reflects the engines that returned this URL, in the order SearXNG provides them. No score is computed on top — the agent is free to read engine count as a corroboration signal or ignore it.

Fetch a URL and return its content. Handles HTML (converted to structured Markdown), PDF (text extracted viapdf_oxide), Office documents (DOCX, XLSX, PPTX, plus legacy DOC, XLS, PPT — converted to Markdown viaoffice_oxide), plain text (charset-decoded), and images (JPEG, PNG, GIF, WebP returned as MCPImageContentblocks for vision-model consumption — SVG is intentionally excluded, since it is more useful to the model as text than as a base64-encoded binary blob). Caches results by default; image responses bypass the text cache.

Both pagination parameters are ignored for image URLs, which are returned whole as image content blocks.

{ "url": "https://example.com/article", "force_refresh": true }

Example — continue reading a long document from where the last response stopped:

{ "url": "https://example.com/big-report.pdf", "start_index": 100000 }

Fetch only the structured metadata for a URL — title, author, publish date, language, site name, description, image, categories, and tags — without returning the page body. For PDFs,page_countis also returned, so an agent can gauge whether a candidate is a 3-page memo or a 400-page report before committing to a full read (it is deliberately absent for Office documents: DOCX has no intrinsic page count, since pagination is computed at render time). Roughly an order of magnitude cheaper in tokens thansearxng_read_url, and intended as a triage step before committing to read a candidate URL in full. Results are cached and the cache is shared withsearxng_read_url: a metadata fetch followed by a content fetch (or vice versa) costs one upstream HTTP request, not two.

Example — triage three candidates before reading one in full:

{ "url": "https://example.com/article-a" } { "url": "https://example.com/article-b" } { "url": "https://example.com/article-c" }

Output shape.A JSON object with the curated metadata fields. Fields the extractor could not populate are omitted rather than rendered as empty strings ornull, so the response is variable-shape; at minimumurlis always present:

<sec:fence xmlns:sec="http://promptfence.org/security/1.0" signature="MEYCIQDx5w2l7..." kid="3f9a1c7e2b4d8056" nonce="a9f7e2c14b8d6f31..." rating="untrusted" source="https://example.com/article" timestamp="2026-05-07T14:23:00Z" type="content" version="1.0"> <extracted content> </sec:fence>

- Key identification and format versioning.Every fence carrieskid— the same fingerprint reported by/fence/public-key— andversion.kidlets a verifier holding several keys select one instead of trial-verifying against all of them, which is what makes key rotation workable: fences signed by an outgoing key stay in the context window and keep arriving while the new key rolls out, and withoutkid"signed by a key I have since retired" and "forged" both present as "nothing in my set verifies this". Both attributes are inside the canonical signed form, so an attacker cannot rewritekidto name a key they control, or downgradeversionto reach an older verification path, without invalidating the signature.
- Boundary-escape protection.Each fence carries a 128-bit randomnonce(fromcrypto/rand). An attacker who controls fetched content cannot guess the nonce, so they cannot forge a closing tag that prematurely ends the fence or open a new "trusted" fence inside it. The awareness preamble tells the consuming model to honour only the boundary identified by the per-response nonce.
- Forward-compatible signatures.Every fence carries an Ed25519 signature so a future fence-verifying client (or an external verifying gateway) can authenticate that fenced content was emitted by this specific server process. The signed bytes are a domain-separated, length-prefixed serialisation —"PromptFence/v1.0" || 0x00 || uint64_be(len(content)) || content || canonical_metadata— fed to PureEd25519 per RFC 8032 §5.1 (the signing operation hashes the message internally with SHA-512; we do not pre-hash). This is a deliberate deviation from paper §4.3's literalEd25519(SHA-256(C || M))construction, which silently changes the security argument by feeding a 32-byte digest into a signature scheme that already hashes its input. The domain tag prevents cross-protocol signature confusion; the length prefix removes the boundary ambiguity a barecontent || canonical_metadataconcatenation would leave. Content is signed in its pre-XML-escape form, so a verifier xml-unescapes the parsed element body before verifying. The exact wire format is documented in thefence.gocomputeFenceSignatureandbuildFenceSigningInputcomment blocks.No MCP client currently verifies these signatures; they are present for forward compatibility.

- Without a verifier, the signatures provide no cryptographic guarantee. Boundary-escape protection comes entirely from the per-response nonce.
- The Prompt Fencing paper measured 100% prevention of direct injection in their experimental setting (n=300 attempts across two frontier models), but that result depends on model compliance with the awareness preamble. Smaller or specialised models may behave differently.
- Semantic attacks — where untrusted content tries topersuaderather thanimpersonate— are not addressed by any fencing scheme.

Public key.The Ed25519 public key for the running server is exposed atGET /fence/public-key(HTTP mode, unauthenticated — a public key is by definition not a secret). The startup banner prints the same key's fingerprint, so the two can be cross-checked. Thatfingerprintfield is also the value each fence carries as itskid, so a verifier can key its trusted-key set on it directly; the field is deliberately not renamed tokidin the endpoint response, since anything already parsing it expectsfingerprint.