How do I use websearch-ring?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@websearch-ring search for MCP server best practices" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

websearch-ring

by TWFU-wcy

Overview Schema Source Related Servers Discussions Admin

JavaScript

Remote

websearch-ring

Release License: MIT

多后端轮询 · 自动故障转移 · Keyless 优先 的网页搜索 MCP Server。

一份 index.js，零 npm 依赖，接到任意支持 stdio MCP 的客户端即可稳定联网搜索——不绑模型、不绑厂商、不强制 API Key。

3 results for "杭州周末天气" (via exa, cached)
1. 杭州天气预报…
   https://…

首行标明实际来源（via exa / tavily / bing），以及是否命中缓存（, cached）或被并发合并（, shared with a concurrent call）。

为什么需要它

痛点	websearch-ring 的做法
单一搜索 API 挂了 / 限流	按环顺序自动换下一家
不想管一堆 API Key	默认 keyless 通道开箱即用
同样 query 被子代理打爆	TTL 缓存 + 相同并发请求合并
出站带用户标识	请求不携带任何用户标识
换模型后内置 websearch 不可用	独立 stdio MCP，客户端无关

Related MCP server: GroundRoute

特性

✅ 厂商轮盘：默认 exa → tavily → bing，失败 / 超时 / 限流自动 failover
✅ Keyless 优先：可选 EXA_API_KEY / TAVILY_API_KEY 提额度
✅ TTL 缓存：默认 20 分钟（WEBSEARCH_TTL_MS）
✅ 并发合并：相同 query 并发只打一次后端
✅ 可审计：via 来源 + 失败 attempts + 截断标记
✅ 单文件：约 400 行，无构建、无 dependencies

快速开始

1. 冒烟测试（可选）

node smoke-test.mjs "杭州周末天气"

预期：第一次结果无 cached，相同参数第二次含 (via …, cached)。

2. 接入（两种通用方式）

路径改成你机器上的绝对路径。

方式 A — CLI（例：Claude Code）

claude mcp add websearch-ring -- node /absolute/path/to/websearch-ring/index.js

方式 B — 通用 mcpServers JSON
（Claude Desktop、Cursor 等；Codex 等 TOML 客户端把同样字段改成对应格式即可）

{
  "mcpServers": {
    "websearch-ring": {
      "command": "node",
      "args": ["/absolute/path/to/websearch-ring/index.js"],
      "env": {
        "WEBSEARCH_VENDORS": "exa,tavily,bing",
        "WEBSEARCH_TIMEOUT_MS": "12000",
        "WEBSEARCH_TTL_MS": "1200000",
        "WEBSEARCH_MAX_CHARS": "12000"
      }
    }
  }
}

任何支持 command + args + env 的 MCP 客户端都是同一套路。

环境变量（全部可选）

变量	默认	说明
`WEBSEARCH_VENDORS`	`exa,tavily,bing`	轮转顺序
`WEBSEARCH_TIMEOUT_MS`	`12000`	单厂商超时
`WEBSEARCH_MAX_CHARS`	`12000`	返回文本上限
`WEBSEARCH_TTL_MS`	`1200000`	缓存 TTL；`0` 关闭
`EXA_API_KEY`	（空）	空则 keyless
`TAVILY_API_KEY`	（空）	空则 keyless
`WEBSEARCH_UA`	Chrome UA	Bing 抓取 UA

调用流程

要点：

优先级：缓存命中 → inflight 合并 → 新跑轮转（不可颠倒）
缓存命中：不写缓存、不续 TTL；attempts: [] + cached: true 直接 render
仅厂商成功 时 cacheSet；合并方与全失败都不写
全失败：正常返回 vendor: null + attempts，仍走 render，isError: true
标记：cached > coalesced（shared）> 空；有失败才出 Note 行

工具接口

Tool: web_search

参数	类型	必填	说明
`query`	string	✅	搜索词
`numResults`	integer		默认 8，钳制 1–20

与同类方案的差异

最轻：单文件、零依赖
Keyless-first，可选补 Key
缓存 + 并发合并 同时具备
via / attempts 透明

最轻量的高可用搜索环：一份 index.js，exa→tavily→bing 自动故障转移 + TTL 缓存 + 并发合并。

许可证

MIT

Available Tools

1 tool

web_searchA

Search the web. Rotates across multiple keyless search backends with automatic failover, so it stays available regardless of which chat model or provider the client uses. Returns titles, URLs and snippets, and reports which backend served the result.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes	Search query
`numResults`	No	Number of results to return (default 8, max 20)

TDQS

A4.3/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does this well: it reveals hidden backend rotation, keyless access, automatic failover, availability rationale, and the exact result fields returned (titles, URLs, snippets) and backend reporting.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: purpose first, then reliability behavior, then return shape. It is tight, front-loaded, and free of filler or redundant restatement.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter search tool with no output schema, the description covers the core purpose, the return format, and the key hidden behavior. Nothing essential is missing for an agent to select and invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents both parameters, including the default and max for numResults, so coverage is complete. The description adds no additional parameter-level meaning beyond what the schema provides, which matches the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a direct verb and resource: 'Search the web.' It immediately clarifies what the tool does, and then adds what results contain (titles, URLs, snippets). With no sibling tools to distinguish from, this is a complete purpose statement.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There are no sibling tools or explicit alternatives to compare against, and the description does not state exactly when to prefer this tool. However, 'Search the web' implies general web-search use cases, and the failover/availability note adds context that it can be used across providers. This is adequate but not explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

1 tool updatev1.0.0Sep 23, 2026
- First observedweb_search

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.3/5.0

Scored 2026-09-23 18:15 across 1 tool

Disambiguation5/5

With only one tool, there is no possibility of overlap or confusion. The tool's purpose is clear and distinct by definition.

Naming Consistency5/5

A single tool named web_search follows a clear verb_noun convention. Consistency is trivially maintained since there are no other tools to conflict.

Tool Count3/5

One tool for a web search server is borderline. While it serves a specific purpose, the lack of any auxiliary tools (e.g., for history, preferences, or pagination) makes the server feel minimal, though not unreasonable for a focused search utility.

Completeness4/5

The tool covers the core search workflow effectively, returning titles, URLs, and snippets. However, it lacks advanced search options (filters, pagination, explicit backend selection) that could round out the surface, though these are not strictly required for basic search.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

web-search
ai.groundroute
Web search for AI agents — one tool across 6 engines, routed to the cheapest + cached.
Search Browser Automation
21
Ninelayer
in.ninelayer
Agent-native search engine with live web research optimized for AI agents.
Search Agent Orchestration
2
qsearch A
io.github.theYahia
Multi-engine search for AI agents. Trust scoring, local corpus, MCP-native. Self-hostable, BYOK.
Search RAG Systems
22
Parallel Search MCP AOAuth
ai.parallel
The best web search for your AI Agent
Search Agent Orchestration Browser Automation
2216

Related MCP Servers

Argus
Search Browser Automation
Khamel83
A
license
B
quality
A
maintenance
One endpoint, five search providers. Search broker for AI agents with automatic fallback, RRF ranking, and budget enforcement. The LiteLLM of web search.
Updated a day ago (2026-09-23 05:28 UTC)
13
97 PyPI
5
MIT
GroundRoute
Search Browser Automation
PROJECT-B-26
A
license
A
quality
D
maintenance
Web search for AI agents across 6 engines (Serper, Brave, Exa, Tavily, Firecrawl, Perplexity) through one search tool. Routes each query to the cheapest engine that clears a quality bar and caches repeats. Hosted, streamable-HTTP, BYOK supported.
Updated 3 months ago (2026-06-19 07:08 UTC)
1
1
MIT
Search MCP Server
Search Version Control
ilgizar-valiullin
A
license
A
quality
C
maintenance
Enables AI agents to perform unified web searches, GitHub, and GitLab searches with caching, reranking, and fallback across multiple providers.
Updated 3 months ago (2026-07-04 22:05 UTC)
4
17 npm
18
MIT
Web Search MCP Server
Browser Automation Web Scraping Search
santhoshkanna812-spec
F
license
Not graded
quality
C
maintenance
Enables AI agents to search the web and extract content using multiple search providers, with caching, retry logic, and options for JavaScript-heavy page rendering.
Updated 2 months ago (2026-07-14 16:53 UTC)
-

websearch-ring

为什么需要它

特性

快速开始

1. 冒烟测试（可选）

2. 接入（两种通用方式）

环境变量（全部可选）

调用流程

工具接口

与同类方案的差异

许可证

Available Tools

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Argus

GroundRoute

Search MCP Server

Web Search MCP Server