Agent Search MCP

Free, token-efficient web search for AI agents. Start with eight zero-key sources. Spend less context through waterfall stopping and compact output. Route Chinese queries natively and escalate to optional commercial APIs only when needed. npx agent-search-mcp is all you need.

中文文档 · Benchmarks · CHANGELOG

Why Agent Search MCP

The immediate value is simple: search without paying for an API, and return fewer tokens without blindly throwing away evidence. The mechanism behind that promise is a search policy for where to search, when to stop, how much context to spend, and what evidence to trust. Agent Search MCP is that control layer: a local-first search router, not another single-backend search API.

The route is deliberate: zero-key start → Chinese-native routing → inspectable multi-source evidence → token-aware progressive search → optional commercial escalation. The 12 adapters serve this route; adapter count is not the product story by itself.

Comparison last checked 2026-07-25 against the linked official repositories. Commercial services have useful free allowances, but still require an account or credential; pricing changes, so this table intentionally avoids monthly-price claims.

Zero-key by default

Eight adapters need no credentials — DuckDuckGo, Sogou, Bing, Baidu, Wikipedia, Startpage, Yandex, and Mojeek. Brave, Tavily, Exa, and You.com remain optional when you want their APIs.

Progressive multi-source search

Parallel and waterfall orchestration, URL/title deduplication, ranking, and graceful fallback are built in. Compact mode supports progressive disclosure so agents can inspect the top results first and call free_extract only when deeper content is needed.

Token control is a product feature

OUTPUT_STYLE=compact, MAX_FULL_RESULTS, SNIPPET_LENGTH, MIN_CONFIDENCE, and MIN_SOURCE_COUNT let operators trade context size against detail. A historical 30-query live run measured 28.7% fewer tokens in Compact mode, 35.5% in Compact+, and 75% fewer engine calls than naive eight-engine fan-out. These are scoped measurements for that query set and environment, not universal guarantees. The new frozen-fixture replay uses an in-process tokenizer and currently measures 30.2% / 33.9% formatting savings reproducibly.

Native Chinese search

Sogou + Baidu search the Chinese web directly — WeChat content, Baidu Baike, Chinese forums. Not a translation layer, not an afterthought.

Quick Start

# One command — no install, no API keys
npx agent-search-mcp

Requires Node.js >= 18.

Client Configuration

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

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

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

mcp_servers:
  agent-search:
    command: npx
    args: ["-y", "agent-search-mcp"]

Engines

The package contains 12 engine adapters, all selectable through free_search, free_search_advanced, the CLI, and waterfall routing. Eight work without credentials; Brave, Tavily, Exa, and You.com are enabled when their API keys are present.

Tools

All tools are read-only and idempotent with MCP 2025 annotations.

Configuration

Environment Variables

Zero config works — the 8 free engines need no API keys.

Tool Visibility

# Only specific tools
ENABLED_TOOLS=free_search,free_search_advanced,free_search_news

# Disable specific tools
DISABLED_TOOLS=free_extract,fetch_github_readme

DISABLED_TOOLS takes priority over ENABLED_TOOLS.

HTTP deployment

HTTP mode is secure-by-default: /mcp requires Authorization: Bearer <token>, and browser requests with an Origin header must match ALLOWED_ORIGINS. Keep /health available for probes, terminate TLS at a trusted reverse proxy, and rotate the token as a secret. See the HTTP deployment guide.

Engine Filtering

ALLOWED_ENGINES=sogou,baidu    # Chinese-only
DENIED_ENGINES=yandex,mojeek   # Exclude specific engines

CLI

agent-search-mcp ships with a standalone CLI (fasm).

# Search
fasm search "TypeScript MCP server"
fasm search "query" --count 5 --engines bing,baidu,youcom --json

# Extract
fasm extract "https://example.com"
fasm extract "https://example.com" --json

# HTTP server (Bearer auth is required for MCP HTTP mode)
HTTP_AUTH_TOKEN=change-me MODE=http npx agent-search-mcp

Benchmark

The benchmark has two evidence tracks. The historical 2026-07-24 live run covers 30 EN/ZH queries and measured 28.7% Compact, 35.5% Compact+, and 75% fewer calls versus naive eight-engine fan-out. Its raw responses were not frozen, so those figures remain historical environment-scoped measurements. The current runner captures actual execution telemetry and replays a frozen fixture through every output style with locked gpt-tokenizer; CI verifies the expected summary (currently 30.2% / 33.9%). Neither track is a cross-product quality ranking or a production guarantee.

→ Methodology, queries, limitations, and reports

Companion Tools

🛡️ mcp-slim-guard — Add security + compression to your MCP stack

npm install -g mcp-slim-guard
mcp-slim-guard init
mcp-slim-guard start

AI Agent → mcp-slim-guard (security + compression) → agent-search-mcp

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 build helper is cross-platform; CI checks Node.js 18/20/22 on Linux and performs a Windows build smoke test.

License

Apache 2.0

Based on open-websearch by Aas-ee.