Search that shows its work

search

A self-hosted MCP server for web search that reports how much of each answer to believe

---

A search tool fails in ways that look exactly like success. An engine answers with somebody else's subject. A page returns text that is an anti-bot shield. Sixteen sources turn out to be two engines counted eight times. None of that raises an error, and the model on the other end builds on it.

This server's job is to make those cases distinguishable, in fields you can branch on. It runs on your machine, over your own metasearch instance, with your own model key — or none at all.

🔧 Tools

Full argument reference, response shapes and failure modes: [HOWTO-CALL.md](HOWTO-CALL.md).

📦 Install

From an open repository page to a working answer. Nothing is assumed to be on your disk already:

git clone https://github.com/AG-Bureau/mcp-search

cd mcp-search cp .env.example .env echo "SEARXNG_SECRET=$(openssl rand -hex 32)" >> .env echo "BROWSER_WS_SECRET=$(openssl rand -hex 16)" >> .env echo '{}' > door-tokens.json && mkdir -p tls docker compose -f docker-compose.yml -f wiring/expose-localhost.yml up -d --build curl -s http://127.0.0.1:8081/healthz

The fourth and fifth lines are not decoration. Without a value in SEARXNG_SECRET the up command refuses — and that refusal is deliberate: with no key of its own the metasearch does not fail, it comes up with a publicly known one from its image template, silently. BROWSER_WS_SECRET is the secret path of the browser sidecar's endpoint, and up refuses without it too: on a guessable path, anything that can open a WebSocket to the sidecar — any container on the compose network, and any page the browser itself opens — gets a browser of its own, outside every check the module applies to the pages it reads. The compose file hands the same value to the sidecar and, at the end of BROWSER_WS_URL, to the adapter; neither prints it.

The sixth line creates the two paths the compose file mounts for caller authentication and TLS — both off by default. A path that does not exist is created by Docker as a root-owned DIRECTORY, and a token "file" that is a directory reads as an unreadable list (see Configuration below). Both are in .gitignore: they hold secrets once you use them.

The overlay publishes the port on loopback only. A published container port does not go through the host firewall's usual chain, so exposing it more widely is a separate, deliberate step — see Deployment.

Two transports

MCP has two, and they answer different questions. HTTP — the commands above — is for a server that is already running somewhere. stdio is the protocol's default: the client starts the server as a process and talks to it through the pipes, which is how most desktop clients and wrappers work.

docker compose exec -T ag-search python /app/server.py --stdio   # or MCP_TRANSPORT=stdio

outside compose: SEARXNG_URL=http:// python adapter/server.py --stdio

One JSON-RPC object per line in, one answer per line out. The mode is chosen explicitly and never guessed from whether a terminal is attached — that sign merely sits next to the subject, and one day it answers for a case nobody meant.

In stdio mode stdout is the protocol: answers and nothing else, with the log on stderr. One stray line of anything else breaks the client reading it.

Each process started this way is an instance of its own, even inside the running container: its browser sessions (BROWSER_MAX_SESSIONS), its engine and domain pacing and its /stats counters are separate from the HTTP server's. Several stdio clients on one sidecar add up in its pids_limit like several adapters do.

The sidecars do not depend on the choice; the metasearch does: SEARXNG_URL must reach one, or every search refuses with cause: upstream (the default, http://searxng:8080, is a name only the compose network knows). Started by a client with no compose project around it, the module names what else is missing instead of pretending: the browser path reports not_wired_up, and trouble carries pool_unmeasured — the engine pool was never computed from observation.

⬆️ Upgrading to 0.3.5 — no new variable

From 0.3.4: the same command as the install block, with the same -f files. Only the adapter image changes (ag-mod-search/adapter:0.3.5, used by the adapter and the prober); the sidecar stays ag-mod-search/browser:1.49.1-3. Two things you may notice: the door now logs one line per request (the caller's address, the path, the status and the caller's token name — never the token, the body or the query string), and a model call that runs out of the time its caller had now returns a refusal that says so instead of running on. From 0.3.3 or earlier, the 0.3.4 steps below apply too.

⬆️ Upgrading to 0.3.4 — no new variable, one stricter one

From 0.3.3: the same command as the install block, with the same -f files. Only the adapter image changed; the sidecar stays ag-mod-search/browser:1.49.1-3. Check AG_DOOR_AUTH first: a value that is not off, warn or on (in any case, spaces around it ignored) now stops the adapter from starting, where it used to mean off. From 0.3.2 or earlier, the 0.3.3 steps below apply too.

⬆️ Upgrading to 0.3.3 — one new required variable

BROWSER_WS_SECRET must be in .env before up: add it as the install block does, with openssl rand -hex 16. Then run the install block's own command, with the same -f files you installed with: docker compose -f docker-compose.yml -f wiring/expose-localhost.yml up -d --build. It rebuilds both images and recreates the adapter, the prober and the sidecar, since the image or the environment of each changed. Name no services on it: up … browser ag-search leaves the prober on the old image, and leaving out the -f overlay recreates the adapter without its published port. The sidecar image is ag-mod-search/browser:1.49.1-3; with the old sidecar, or with only one side recreated, the browser path reads "not responding".

A malformed secret stops the whole module. Compose checks only that the value is not empty. Characters outside A-Z a-z 0-9 _ - (base64 gives + / =) make the sidecar exit with 78 in a loop; the adapter waits for a healthy sidecar, so it never starts and up says "dependency failed to start".

If you run the door in warn or on, also read "Moving to on" under Configuration: the prober now takes a token, a token with no scopes (or with scopes written as a string) may call no tool, and /healthz?deep=1 needs a token that may search or read.

⬆️ Upgrading from 0.2.x — the answer changed shape

If you already run 0.2.1 or earlier, read this before updating. Nothing here is a new feature you may ignore; it is what your existing calls will return differently.

The search and image answers carry fewer fields by default, and they say so in their name: ag.search/3 and ag.images/3 instead of /2. A caller that branched on contract will break loudly, which is the intent — a field that simply vanished would read as "nothing was wrong" in most languages.

trouble is always present and empty when nothing went wrong, so if not trouble replaces the four separate checks. Nothing was deleted from the module — the accounting moved behind a request.

Booleans are now parsed rather than cast. In 0.2.x "read": "false" over MCP read the pages anyway — eight times the wall clock — while the plain door understood the same word correctly. Both doors now accept true/false, 1/0, yes/no, on/off, y/n, t/f and Python's True/False, case-blind. A value that cannot be read turns the flag off and is named in `arguments_adjusted`, and an EMPTY value counts as unreadable: read="" no longer buys the expensive default in silence.

`read_top: 0` means "no preference", not "read nothing" — for nothing, use read: false. The schema used to declare minimum: 1 while accepting zero.

The field-by-field table is in the contracts: contracts/ag.search.v3.md and contracts/ag.images.v3.md, section "What changed against /2". Reading (ag.read/2), deep search (ag.deep/2) and screenshots (ag.shot/1) kept their numbers: they gained fields, and an addition breaks nobody.

⚙️ Configuration

| LLM_API_BASE | no | Base URL of that endpoint. Take it from your provider's documentation, not by analogy — the obvious guess can answer with a billing error such as 429: Insufficient balance, because some providers serve a subscription on a different