Agent Search MCP: Free-first Web Search with Inspectable Evidence
A Node.js MCP server and CLI for English and Chinese web search.
Agent Search MCP starts without an API key. It returns compact multi-source
evidence, records provider failures, and bounds work with request and evidence
budgets. Paid providers run only when policy and credentials allow.
Free-first Chinese and English web search MCP using zero-key sources and inspectable evidence.
Invoke it with a request such as Use $agent-search to verify this claim with official sources. The Agent Search Skill
chooses one of four bounded paths: quick discovery, stricter verification,
Chinese-source search, or extraction of a selected URL. It checks that the
needed MCP tool exists and asks before any install or configuration change.
Installing the Skill does not start or configure the MCP server.
Example: inspect a bounded search result
After building the local package, run a CLI query without adding a provider key:
npm run build
fasm search "MCP server without an API key" --json
The response contract keeps result evidence, meta.execution, and
partialFailures separate. A provider timeout or challenge remains visible to
the agent instead of being converted into an unexplained empty result. This is
a contract example, not a live availability or search-quality benchmark.
After a global install, check the local runtime without making a search request:
npm install -g agent-search-mcp
fasm doctor
Why Agent Search MCP
Need
Product behavior
Free web search
Zero-key sources work without an API account
Provider cost control
Paid providers run only under an explicit routing policy
Token cost control
Compact output and one evidence budget bound response size
Multi-source evidence
Results retain provenance, relevance, provider-family count, and partial failures
Chinese web search
Sogou and Baidu handle Chinese queries without a translation layer
Lightweight self-hosting
Pure Node.js runtime with stdio, Streamable HTTP, and CLI access
The difference from a plain multi-engine wrapper
Plain multi-engine aggregation
Agent Search MCP
Returns N deduplicated results
Returns results plus the number of independent sources (provider families, not adapter names)
A provider failure quietly drops some results
Every failure stays in partialFailures (timeout, rate limit, challenge, permission, budget)
Stops when the result count looks sufficient
Stops only after a quality gate (count, relevance, confidence, source coverage) and returns the stop_reason
Fixed-size output
One shared evidence budget bounds response tokens; compact text keeps provenance
One adapter counts as one source
The same upstream through several adapters never inflates source_count
The one-minute offline demo replays these differences through the production
evidence scorer and formatter:
Inspect the search evidence
Each JSON response includes one Search Evidence Packet. It answers the routing
questions an agent needs before it uses a result:
Question
Response field
Which adapters ran?
meta.execution.searched_engines
Why did the router stop?
meta.execution.stop_reason and meta.execution.quality_gate
Did the request hit a work limit?
meta.execution.budget
Was evidence truncated?
meta.evidence_budget
Did an upstream provider fail?
partialFailures
Do multiple adapters represent independent sources?
results[].source_count counts provider families, not adapter names
Run the one-minute offline contract demo:
npm run demo:evidence
npm run demo:evidence -- --json
It replays three synthetic scenarios through the production evidence scorer,
formatter, and MCP output helper: same-family adapter overlap, visible fallback
failure, and a bounded quality-gate stop. It makes no live availability or
search-quality claim and performs no network request.
The default free_first policy never spends a configured API credential.
free_only blocks paid providers. quality_escalation can call one configured
paid provider after free evidence misses the quality gate, while paid_first
tries that provider before the free fallback.
Request budgets cap adapter attempts, elapsed time, and admitted results.
The evidence budget caps query-relevant passages across the complete response.
Compact mode keeps full detail for the first results and reduces later entries
to source-preserving references.
Measured token reduction
The checked-in bilingual fixture measures formatting with a locked tokenizer:
Output
Average tokens per query
Savings vs normal
Normal
2396.0
Compact
1650.1
31.1%
Compact+
1633.0
31.8%
This fixture verifies output formatting and evidence-packet behavior. It does
not measure live engine availability or search quality. See the
benchmark method and limitations.
How the search router works
flowchart LR
A["AI agent"] --> M["MCP search tools"]
M --> P["Provider and request policy"]
P --> F["Zero-key sources"]
P --> O["Optional paid provider"]
F --> E["Deduplicate, rank, and preserve failures"]
O --> E
E --> B["Evidence and token budget"]
B --> R["Compact multi-source result"]
The router evaluates each search batch against separate result, relevance,
confidence, and provider-family gates. It stops after the evidence passes those
gates and exposes the decision in meta.execution. Provider failures stay
visible in partialFailures, so an empty result cannot hide an upstream error.
The competitive landscape (2026-08-07)
maps the crowded baseline and the product gaps. It records source dates and
fixed commits for facts that can change. The
2026-08-10 update
adds competitor activity since then: direct local competitors are dormant, and
token-efficient evidence is becoming an industry-explicit lever. The earlier
source-level product comparison
contains the architecture-specific evidence.
Engines
The runtime registers 16 adapters: 9 zero-key adapters and 7 optional API adapters.
Engine
Access
Languages
Role
DuckDuckGo
Zero-key
en
General Web Search
Sogou Search
Zero-key
zh
Chinese Web Search
Bing
Zero-key
en, zh
Multilingual Web Search
Baidu
Zero-key
zh
Chinese Web Search
Wikipedia
Zero-key
en, zh, ja, de, fr, es, auto
Encyclopedic references
Startpage
Zero-key
en, auto
Privacy-oriented Web Search
Yandex
Zero-key
ru, en, auto
Russian and international Web Search
Mojeek
Zero-key
en, auto
Independent privacy-oriented index
Wiby
Zero-key
en
Independent small-Web index
Brave Search
BRAVE_API_KEY
en, zh
Optional commercial Web Search
Tavily Search
TAVILY_API_KEY
en, zh
Optional agent-oriented Search
Exa Search
EXA_API_KEY
en, zh
Optional neural Search
You.com Search
YDC_API_KEY
en, zh
Optional commercial Web Search
Tencent Web Search API
TENCENT_WSA_API_KEY
zh
Optional official Chinese Web Search
Bocha Web Search
BOCHA_API_KEY
zh, en
Optional Chinese-first AI Search
Serper Google Search
SERPER_API_KEY
en, zh, auto
Optional Google SERP Search
Tools
Tool
Description
Best for
free_search
Multi-engine Web Search with bounded fallback
Quick facts and general discovery
free_search_advanced
Filtered waterfall search and optional enrichment
Domain policy and progressive verification
free_extract
Extract a URL as clean Markdown
Reading complete source pages
fetch_github_readme
Fetch a public GitHub repository README
Project documentation
fetch_csdn_article
Fetch a CSDN article
Chinese technical articles
fetch_juejin_article
Fetch a Juejin article
Chinese developer articles
search_with_synthesis
Search evidence with an LLM synthesis hint
Agent-authored answers from cited evidence
Capability controls
Environment
Default
Purpose
ENABLED_TOOLS / DISABLED_TOOLS
all / none
Tool registration allowlist and denylist; deny wins
ALLOWED_ENGINES / DENIED_ENGINES
all / none
Engine execution allowlist and denylist; deny wins
SEARCH_PROVIDER_MODE
free_first
Default routing: free_first, quality_escalation, paid_first, or free_only
PAID_ENGINE_ORDER
brave,exa,tavily,youcom,tencent_wsa,bocha,serper
Selects the first configured optional provider; not a quality claim
SEARCH_BUDGET_MAX_CALLS
16
Adapter-attempt budget
SEARCH_BUDGET_MAX_ELAPSED_MS
30000
End-to-end elapsed-time budget
SEARCH_BUDGET_MAX_RESULTS
100
Admitted raw-result budget
EVIDENCE_BUDGET_CHARS
1200
Evidence-character budget
search_with_synthesis uses the same canonical structuredContent evidence
packet as the primary search tools and adds prompt_hint; its text content is
only a compact compatibility view. Execution metadata distinguishes scheduled
adapters from retry-inclusive adapter attempts. http_requests is null until
all adapter transports can report it without false precision.
Wiby is a genuine zero-key source backed by its official JSON API and is used
late in the free waterfall as an independent small-Web supplement. Optional
providers require user credentials; any signup credit or trial quota is
provider-controlled and is not treated as permanent free access.
All tools are read-only and idempotent. Search cancellation reaches rate-limit
waits, retries, provider requests, and optional enrichment. Enrichment can
improve a snippet but cannot increase source confidence or independent source
count.
free_search_advanced.time_range remains in the compatibility schema. The
server returns UNSUPPORTED_FILTER before searching because the general web
providers do not share one enforceable recency contract.
Configuration
The generated capability table above lists the default request budgets. These
settings cover the common deployment choices:
Goal
Environment variables
Add an optional provider
BRAVE_API_KEY, TAVILY_API_KEY, EXA_API_KEY, YDC_API_KEY, TENCENT_WSA_API_KEY, BOCHA_API_KEY, or SERPER_API_KEY
Adding an API key does not authorize paid traffic. The routing policy controls
provider use. The default exact-result cache stays in memory; setting
SEARCH_CACHE_DIRECTORY opts into local persistence. Semantic processing is
the only optional feature that uses Python and Model2Vec.
Proxy pools select a deterministic first exit from the logical query and keep
multi-step provider requests sticky. Only a transport failure can move to the
next configured exit; a failed transport is cooled for 60 seconds. HTTP
responses, including 403, 429, and challenge pages, never trigger proxy
switching and continue through the provider's existing cooldown contract.
Engine-specific single-proxy variables take precedence over their pool. Proxy
credentials are never printed by fasm doctor.
HTTP deployment
HTTP mode requires HTTP_AUTH_TOKEN unless you set
HTTP_ALLOW_UNAUTHENTICATED=true. Browser requests with an Origin header must
match ALLOWED_ORIGINS. See the HTTP deployment guide
for TLS termination, token rotation, and reverse-proxy examples.
Agent Search controls retrieval work and compresses search evidence.
mcp-slim-guard sits between an
agent and MCP servers to handle tool-schema compression and security policy.
npm install -g mcp-slim-guard
Development
git clone https://github.com/lennney/agent-search-mcp.git
cd agent-search-mcp
npm install
npm run build
npm test
npm run dev # stdio mode
npm run dev:http # HTTP mode (port 3000)
The stable package supports Node.js 18, 20, and 22. The isolated MCP 2026
experiment requires Node.js 20 or newer.