Agent Search MCP

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 17 adapters: 9 zero-key adapters and 8 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 rem