agentsearch-mcp

agentsearch-mcp

面向 AgentSearch API 的远程 MCP（Model Context Protocol）连接器——这是一个原生支持大模型/MCP 的 Web 工具包，适用于 Agent 和 RAG 工作流，提供网页搜索（抽象搜索提供商的 SERP）、无需密钥的即时答案，以及获取 URL → 适用于大模型上下文窗口的干净文本/Markdown。

在线服务： https://agentsearch-mcp.vercel.app/mcp——包含 3 个工具，每个工具对应一个 AgentSearch /v1 端点。由于上游 AgentSearch 部署按量计费（RapidAPI/Apify），并通过 RapidAPI 代理密钥保护 /v1/*，因此此连接器使用同一密钥验证其发出的请求（AGENTSEARCH_MCP_PROXY_SECRET，作为 X-RapidAPI-Proxy-Secret 标头发送），并实施软性 IP 速率限制（AGENTSEARCH_MCP_RATE_LIMIT，默认每小时 30 次工具调用，基于内存），使免费的 MCP 层保持为发现渠道，而非绕过付费服务的无限制通道——详见 lib/ratelimit.js。

这是什么，以及为什么它是独立的连接器

AgentSearch API 是一个普通的 REST API。任何 HTTP 客户端都可以直接调用它。创建此仓库是因为 MCP 客户端（Claude、ChatGPT 和其他支持 MCP 的 Agent）不会使用任意 REST API——它们使用 MCP 工具。 agentsearch-mcp 是一个轻量级适配层，用于：

• 将每个 AgentSearch 端点公开为可发现、类型化的 MCP 工具（名称、描述、zod 输入架构、注释），供大模型推理并直接调用，而无需在其他地方教会它 REST 接口。
• 通过单个 /mcp 端点提供 MCP 流式 HTTP 传输，因此只需一个 URL，即可将其注册为 Claude、ChatGPT 或任何其他 MCP 客户端中的连接器。
• 不做其他任何事情。它没有自己的业务逻辑——每次工具调用都是转发到 AgentSearch 的 fetch，并将 AgentSearch 返回的 JSON 响应原样作为工具结果返回。

按量计费 API 上的免费发现层

此连接器是按量计费的 AgentSearch API 前端的免费发现/增长层。上游（agentsearch-api.vercel.app）通过 RapidAPI/Apify 销售；此 MCP 封装器使用共享的 RapidAPI 代理密钥进行身份验证，并按 IP 限制用量，使其成为体验入口，而非绕过付费方案的无限制通道。大量或生产环境用量应通过 AgentSearch on RapidAPI/Apify 使用。

身份验证：MCP 端无需身份验证（有意如此）

AgentSearch 的数据没有按用户区分——它是公开的 Web 数据（SERP 结果、DuckDuckGo 即时答案、清理后的页面文本）。没有需要按调用者限制访问的内容，因此此连接器有意不提供：

• 不为 MCP 调用者提供 OAuth、登录或 Bearer 令牌
• 不使用 Supabase / 数据库
• 不区分演示账户和真实账户——每位调用者获取的都是真实的实时数据

api/mcp.js 会为每个请求创建一个全新的无状态 McpServer，并且不进行任何 MCP 调用者身份验证。唯一的出站身份验证是上文所述的上游 RapidAPI 代理密钥，该密钥由连接器在服务端持有。

工具列表

每个 AgentSearch /v1 端点对应一个工具（来自 agentsearch-api/openapi.yaml；有意不封装 /api/health）：

工具	AgentSearch 端点	描述
web_search	GET /v1/search	通过抽象搜索提供商的后端（Brave 或 Serper）进行 Web SERP 搜索。返回经过规范化的结果，包含位置、标题、URL、摘要和域名。
instant_answer	GET /v1/answer	无需密钥的 DuckDuckGo 即时答案——定义、实体、简要事实。
fetch_url	GET /v1/fetch	无需密钥，并带有 SSRF 防护；获取 URL → 适用于 RAG 的干净、无模板文本或 Markdown。

这 3 个工具均为只读，并标注为 { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }——它们不会写入任何内容，且返回的数据都来自实时、会在外部发生变化的 Web。

它如何封装 agentsearch-api

每个工具处理程序都会通过普通的 fetch(\${AGENTSEARCH_MCP_API_BASE_URL}${path}`, ...)` 请求调用真正的 AgentSearch REST API，并将解析后的 JSON 作为 MCP 工具结果内容返回：

{ content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }

出站请求会携带 X-RapidAPI-Proxy-Secret: <AGENTSEARCH_MCP_PROXY_SECRET>，以通过 /v1/* 上游防护。上游 HTTP 错误（4xx/5xx）会被捕获，并通过 asError 助手以类型化的 MCP 错误结果呈现，而不会导致请求崩溃。

环境变量

变量	默认值	用途
AGENTSEARCH_MCP_API_BASE_URL	https://agentsearch-api.vercel.app	上游 AgentSearch 基础 URL（用于覆盖，以进行本地/可自托管测试）。
AGENTSEARCH_MCP_PROXY_SECRET	(empty)	RapidAPI 代理密钥，将作为 X-RapidAPI-Proxy-Secret 发送，以通过上游 /v1/* 防护。没有此密钥时，受保护的路由会返回 403。
AGENTSEARCH_MCP_RATE_LIMIT	30	每小时按 IP 计算的 tools/call 软上限（内存中，按无服务器实例分别计算）。

项目结构

api/mcp.js       MCP endpoint (StreamableHTTPServerTransport, stateless, no MCP-caller auth)
api/health.js    GET /api/health
lib/tools.js     All 3 tool definitions (zod schemas + fetch-and-forward handlers, proxy-secret auth)
lib/ratelimit.js Soft per-IP tools/call rate limiter
local-server.js  Plain-Node http server for local dev / smoke testing (not deployed)
test/smoke.mjs   Real end-to-end smoke test (initialize, tools/list, tools/call)
vercel.json      Routes /mcp -> api/mcp.js, /health -> api/health.js
server.json      MCP registry manifest

本地开发

npm install
npm run dev          # starts local-server.js on :3900
npm run smoke        # runs test/smoke.mjs against the local server

若要通过上游防护进行真实的端到端请求，请先设置代理密钥：

export AGENTSEARCH_MCP_PROXY_SECRET=<the RapidAPI proxy secret>
npm run dev &
npm run smoke