agent-search-mcp

Purpose

Agent Search MCP is a Node.js MCP server and CLI for web search in English and Chinese. It is designed with a "free-first" goal, runs by default without any API keys, and also requires no browser, database, Python, or search API account. This tool is suitable as a retrieval component for AI agents, allowing agents to check evidence quality and routing decisions before invoking search results.

Main Capabilities

• Multi-source search: 16 adapters are registered at runtime, of which 9 are zero-key adapters and 7 are optional API adapters. Zero-key sources include DuckDuckGo, Sogou, Bing, Baidu, Wikipedia, Startpage, Yandex, Mojeek, etc., with Wiby used later in the free waterfall as an independent supplementary source for small web pages.
• Evidence packet: Each JSON response includes a Search Evidence Packet, returning compact multi-source evidence and recording provider failures. Result evidence, meta.execution, and partialFailures remain separate, so provider timeouts or challenges do not become unexplained empty results.
• Routing strategies: The default free_first strategy does not consume configured API credentials; free_only blocks paid providers; quality_escalation calls one configured paid provider after free evidence fails to pass the quality threshold; paid_first tries that paid provider first.
• Budget control: The request budget limits adapter attempts, elapsed time, and the number of included results; the evidence budget limits the number of query-related passages in the entire response. Compact mode preserves full detail for the first batch of results, while subsequent entries are reduced to citations that retain the source.
• Offline demo: Provides a one-minute offline contract demo that replays three synthetic scenarios (overlap among same-family adapters, visible fallback failure, and bounded quality-gate stop) through the production evidence scorer and formatter, without making network requests.
• Capability control: search_with_synthesis uses the same canonical structured content evidence packet as the main search tool and adds prompt_hint. All tools are read-only and idempotent, and search cancellation can apply to rate-limit waits, retries, provider requests, and optional enhancements.
• HTTP deployment: HTTP mode requires HTTP_AUTH_TOKEN, unless HTTP_ALLOW_U is set.NAUTHENTICATED=true. Browser requests with an Origin header must match ALLOWED_ORIGINS.
• CLI: The package includes the fasm command-line tool; fasm doctor can read local configuration without performing network probes, and does not print credentials or proxy values.

Usage

Connect using the stdio configuration in MCP clients that support mcpServers JSON (including Claude Desktop, Cursor, VS Code, and Windsurf). Claude Code and Codex can register the same npx -y agent-search-mcp stdio command through their MCP settings.

After connecting to the MCP server, clients compatible with Agent Skills can install the routing guide (Agent Skill) included in the repository, and invoke it through requests like "Use $agent-search to verify this claim with official sources." The Skill selects one of four bounded paths: quick discovery, stricter verification, Chinese source search, or extraction of selected URLs. It checks whether the required MCP tools exist and asks before any installation or configuration change. Installing the Skill does not start or configure an MCP server.

After building the package locally, CLI queries can be run without adding provider keys. After global installation, the local runtime can be inspected without issuing search requests.

Applicable Scenarios

• AI agents need Chinese and English web search capabilities and want a quick zero-key start.
• Search results need multi-source verification, with inspectable evidence and failure records retained.
• Policy-based routing between free and paid search providers is needed, with control over request and evidence budgets.
• Development or testing scenarios need offline verification of search contracts and formatting behavior.
• Scenarios need to deploy an HTTP search service and configure authentication and origin restrictions.

Limitations

• Requires Node.js >= 18.17; the default runtime does not require a browser, database, Python, or a search API account. The stable package supports Node.js 18, 20, and 22; the isolated MCP 2026 experiment requires Node.js 20 or later.
• Optional providers require user credentials; any registration giftsor trial quotas are controlled by the provider and are not considered permanent free access. Adding an API key does not authorize paid traffic; routing policy controls provider usage.
• free_search_advanced.time_range remains in compatibility mode, but the server returns UNSUPPORTED_FILTER before searching because general web providers do not share an enforceable freshness contract.
• http_requests is null until all adapter transports can report it without false positives.
• The proxy pool selects a deterministic first egress from the logical query and keeps multi-step provider requests sticky; only transport failures can move to the next configured egress, and a failed transport cools down for 60 seconds. HTTP responses (including 403, 429, and challenge pages) never trigger proxy switching.
• Semantic processing is the only optional feature that uses Python and Model2Vec.
• By default, exact-result caching is kept in memory; setting SEARCH_CACHE_DIRECTORY enables local persistence.
• Enhancement can improve summaries, but cannot increase source confidence or the number of independent sources.
• The evaluation fixtures for offline demos and inspection only verify output formatting and evidence bundle behavior; they do not measure live engine availability or search quality.
• Built on Aas-ee's open-websearch.