lennney/agent-search-mcp

**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
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:
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:
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:
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:
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:
It replays three synthetic scenarios through the production evidence scorer,