Agent Search MCP

What lennney/agent-search-mcp MCP server does

The lennney/agent-search-mcp MCP server exposes web research capabilities for English and Chinese queries. Its tools cover several levels of work:

• free_search performs general search with a chosen adapter set and bounded fallback.
• free_search_advanced adds domain filters and quality controls, including high-confidence and Chinese-content use cases.
• free_extract retrieves a page through Jina Reader and returns cleaned Markdown.
• fetch_github_readme reads a repository README from GitHub.
• fetch_csdn_article and fetch_juejin_article retrieve content from named Chinese developer-content platforms.
• search_with_synthesis performs deeper, multi-engine verification and returns structured evidence plus a prompt_hint; it does not call an external language model.

The project also provides a command-line interface. The default runtime is free to use without a search API account, browser, database, or Python installation. Optional commercial providers may be enabled with their own credentials, but they are not needed for the zero-key search path.

How it works

The lennney/agent-search-mcp MCP server uses a waterfall search strategy. It tries policy-allowed adapters progressively rather than treating every adapter as an independent source. Adapters connected to the same upstream provider family are attempted sequentially and do not inflate corroboration counts.

Search results are deduplicated and ranked with separate relevance, confidence, and provider-family source counts. The router can stop after result, relevance, confidence, and source-coverage gates pass. Request budgets limit adapter attempts, elapsed time, and admitted results, while an evidence budget limits the amount of query-relevant material returned. Compact output preserves provenance while reducing detail in later results.

Provider problems remain visible in partialFailures, including conditions such as timeouts, challenges, rate limits, permission failures, and budget limits. Search responses also expose execution information such as searched engines, the stop reason, quality-gate status, and budget state. Outbound requests include injection detection and SSRF protections where applicable.

free_extract sends the target URL to Jina Reader at r.jina.ai, which fetches and converts the page. Private addresses, localhost, and metadata endpoints are blocked, and the request timeout is 10 seconds. GitHub, CSDN, and Juejin tools make requests to their respective remote content endpoints.

Setup and configuration

Install the lennney/agent-search-mcp MCP server with Node.js 18.17 or newer:

npx -y agent-search-mcp

MCP clients that accept mcpServers JSON can launch it over stdio:

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

The documented client examples include Claude Desktop, Cursor, and Windsurf. The same stdio command can also be registered in Claude Code and Codex. No credential is required for the default free-first configuration. Optional provider API keys are used only when the relevant provider and routing policy permit escalation; the supplied material specifically names BRAVE_API_KEY, TAVILY_API_KEY, and EXA_API_KEY among optional provider credentials.

Tools and capabilities

Use free_search for quick discovery when domain and date filters are unnecessary. Use free_search_advanced when filtering or stricter evidence quality matters. Use search_with_synthesis for complex questions that need multi-source checking before an agent writes its own answer.

Use free_extract after finding a relevant URL and needing the page’s full context. It is not intended as a bulk-extraction workflow. The specialized fetchers are more direct choices for GitHub READMEs, CSDN articles, and Juejin articles.

The project supports free search adapters including DuckDuckGo, Sogou, Bing, Baidu, Wikipedia, Startpage, Yandex, Mojeek, and Wiby. The README also documents optional API-backed adapters. Chinese queries can use Chinese-oriented sources without requiring a translation layer.

Limitations and notes

Simple searches should use free_search; advanced filtering and verified-only requirements belong with free_search_advanced. Search availability and quality depend on the upstream engines, and failures are reported rather than hidden. free_extract can fail when a page exceeds the 10-second timeout or returns an HTTP error. It also depends on Jina Reader fetching the target page successfully.

The project’s evidence and token measurements are based on checked-in fixtures and do not establish live engine availability or search quality. Installing the optional Agent Skill does not start or configure the MCP server; it provides routing guidance for compatible Agent Skills clients instead.