searxng-mcp-go/docs/adr/004-mcp-stdin-env-only.md
xlion-bot-renovate[bot] 5eb419f9e1
fix(deps): update module github.com/modelcontextprotocol/go-sdk to v1.7.0 (#542)
* fix(deps): update module github.com/modelcontextprotocol/go-sdk to v1.7.0

* fix: support MCP SDK v1.7 first messages

---------

Co-authored-by: xlion-bot-renovate[bot] <218815870+xlion-bot-renovate[bot]@users.noreply.github.com>
Co-authored-by: XLion <[email protected]>
2026-08-02 22:13:27 +08:00

3.7 KiB

ADR-004: MCP Stdin Mode Is Detected From Input

  • Date: 2026-04-19
  • Status: Accepted

Context

The searxng-mcp-go server operates in two modes:

  1. CLI mode: Interactive command-line usage with flags like --query, --json, --searxng-url, etc.
  2. MCP stdin mode: Headless operation communicating via stdio with MCP clients (e.g., Claude Desktop).

The server now detects MCP stdin mode by inspecting the first line of stdin for a supported MCP first message. The preflight accepts a legacy initialize request, a server/discover request, or a stateless request carrying params._meta["io.modelcontextprotocol/protocolVersion"]. It is a bounded structural gate; complete protocol metadata validation remains with the MCP SDK. If the process was launched with CLI arguments, it runs in CLI mode instead. This avoids treating normal command-line usage as MCP input and matches the actual startup flow:

Detection Flow

  1. CLI arguments are parsed first.
  2. Any argument selects CLI mode, including positional queries, search flags, configuration flags such as --searxng-url or --timeout, --debug, --help, and --version.
  3. Otherwise the process reads the first line of stdin and requires one of the supported MCP first-message shapes: legacy initialize, server/discover, or stateless protocol-version metadata in params._meta["io.modelcontextprotocol/protocolVersion"].
  4. If stdin does not look like MCP input, startup fails with an MCP-specific error.

Decision

In MCP stdin mode, configuration comes from environment variables and MCP input, not from standalone CLI search flags. The supported environment variables are:

Environment Variable Purpose
SEARXNG_URL SearXNG server URL
DEBUG Set to 1 for debug logging
SEARXNG_TIMEOUT Sets the search timeout (default 8s)
SEARXNG_MAX_RETRIES Sets the max retry count (default 5)
SEARXNG_ALLOW_GET_FALLBACK Set to 1 to opt in to POST→GET fallback

--help and --version trigger CLI mode for informational output. Like every other CLI flag, they are not accepted in MCP stdin mode.

The JSON first-message wire bytes have a fixed 1 MiB transport bound, independent of the message type, payload, or configuration. An optional trailing newline delimiter is excluded from the count. The preflight only checks safe structure; the MCP SDK validates the complete protocol metadata after startup.

Detection Logic

MCP stdin mode = no command-line arguments

If stdin does not contain a supported MCP first message, the server exits with:

stdin does not contain a valid MCP first message

CLI mode is unaffected

All existing CLI flags continue to work normally. Only the MCP stdin code path enforces the stdin protocol check.

Consequences

Positive

  • Clear configuration contract: MCP users know exactly where to configure the server (environment variables only).
  • Predictable behavior: No silent failures or ignored flags in MCP mode.
  • Better error messages: Users who accidentally pass flags get an immediate, actionable error instead of silent misconfiguration.
  • Easier debugging: When troubleshooting MCP issues, the configuration source is unambiguous.
  • Convention compliance: Aligns with how other MCP servers are typically configured.

Negative

  • Migration required: Existing setups that pass CLI flags in MCP mode (e.g., ./searxng-mcp-go --searxng-url https://example.com) must migrate to environment variables.
  • Less flexible: Users who preferred CLI flags for MCP configuration lose that option. However, environment variables are equally powerful and more portable across MCP client launchers.