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.

中文文档 · Product page · Benchmarks · Architecture · CHANGELOG

Install

npx -y agent-search-mcp

Requires Node.js >= 18.17. The default runtime does not require a browser,

database, Python, or a search API account.

Connect an MCP client

Use this stdio configuration in MCP clients that accept `mcpServers` JSON,

including Claude Desktop, Cursor, VS Code, and Windsurf:

{
  "mcpServers": {
    "agent-search": {
      "command": "npx",
      "args": ["-y", "agent-search-mcp"]
    }
  }
}

Claude Code and Codex can register the same `npx -y agent-search-mcp` stdio

command through their MCP settings.

Add the optional Agent Skill

After connecting the MCP server, Agent Skills-compatible clients can install

the repository-owned routing guide:

npx skills add lennney/agent-search-mcp --skill agent-search

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

The difference from a plain multi-engine wrapper

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:

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:

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.

Tools

Capability controls

`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:

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.

CLI

The package includes the `fasm` CLI:

fasm search "TypeScript MCP server"
fasm search "query" --count 5 --engines bing,baidu,youcom --json
fasm extract "https://example.com"
fasm extract "https://example.com" --json
fasm doctor
fasm doctor --json
HTTP_AUTH_TOKEN=change-me MODE=http npx agent-search-mcp

`fasm doctor` reads local configuration without network probes and never prints

credential or proxy values.

Documentation and evidence

Companion: Slim Guard

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.

License

Apache 2.0

Based on open-websearch by Aas-ee.

If Agent Search MCP helps your agent, star the repository

so other developers can find the project.