给 Claude Code 接入免密钥网页搜索

给 Claude Code 接入联网搜索，可以从一条命令开始。原文介绍的 AgentSearch 通过 MCP 提供搜索工具，不用注册账号或申请 API key，默认每个 IP 每天最多搜索 25 次。它适合查近期文档、找迁移指南，再结合仓库代码判断影响。

但「免费搜索」有边界：返回的是摘要，读取完整网页和渲染 JavaScript 页面需要付费。文章真正值得读的，是它把接入、团队共享、付费开关和排错串了起来，尤其讲清了 1.3.5 与旧版本的收费差异。

一条命令接上搜索，实际接入了什么

AgentSearch 的 npm 包是 @agentsearchhq/agentsearch-mcp，原文称它已列入官方 MCP Registry。作者在 Linux、Claude Code 2.1.309、Node.js 20、包版本 1.3.5 上运行了文中的全部命令，还直接通过 stdio 验证了工具列表、免费搜索，以及钱包配置前后的行为。

先确认 claude --version 能输出版本，node -v 为 Node.js 20 或更新版本，并且启动 Claude Code 的环境能找到 npx。然后在项目目录运行：

claude mcp add agentsearch -- npx -y @agentsearchhq/agentsearch-mcp

需要看懂的是 --：后面的内容属于服务启动命令，避免 -y 被当成 Claude Code 的参数。-y 用来跳过 npx 安装确认，因为后台进程无法等待你回答。

默认采用 stdio 传输，即 Claude Code 启动一个本地子进程，通过标准输入、标准输出通信，不用自己管理端口。这里的「本地」指 MCP 进程运行的位置，联网搜索仍要访问外部服务。

服务提供 5 个工具：agentsearch_web_search 搜索网页；agentsearch_extract 提取网页正文；agentsearch_render 用无头浏览器加载需要执行 JavaScript 的页面；agentsearch_review_lookup 和 agentsearch_review_submit 用于读取、分享代理撰写的工具评价。

搜索每次最多返回 5 条结果，包括标题、URL 和摘要，max_results 可设为 1 到 5。Extract 返回干净的 Markdown 或文本；Render 还可返回 HTML、链接或截图。

搜索摘要足够帮你找入口，却不能替代完整文档。

团队能共享配置，但每个人仍要确认

默认添加范围是 local，只用于当前项目的个人配置。--scope 或 -s 还支持 project、user：前者把配置写到项目根目录 .mcp.json，方便提交到 Git；后者让当前机器上的所有项目都能使用。

团队接入时，把首条命令改为 claude mcp add --scope project agentsearch -- npx -y @agentsearchhq/agentsearch-mcp 即可。每位成员首次打开项目，仍需批准项目级服务。误拒绝后，可以用 claude mcp reset-project-choices 恢复提示。

同名配置的优先级是 local > project > user。如果改了 .mcp.json 却没生效，除了重启会话，还要检查是否被个人配置覆盖。

验证连接用 claude mcp list，查看范围、命令和环境变量用 claude mcp get agentsearch；会话内输入 /mcp，检查状态和工具列表。

原文给出的使用方向很贴近日常开发：搜索 Vite 最新稳定版并对照 package.json，找到 Express 5 官方迁移指南并检查 src/server.ts，或者检索 Node.js test runner 文档。关键是让问题同时包含「外部资料」和「仓库里的判断对象」，搜索才容易转化成具体工作。

Claude Code 会自行决定是否调用工具，首次使用会请求许可。若只想放行搜索，可在 .claude/settings.json 的 permissions.allow 中加入 mcp__agentsearch__agentsearch_web_search，没有必要因此放开文件修改和命令执行。

免费和付费之间，最容易踩的是环境变量

免费额度按 IP 计算，每天最多 25 次，还受共享每日容量限制。办公室共用出口 IP 时，不能理解成每位开发者各有 25 次。

在 1.3.5 中，设置钱包私钥只会启用付费 Extract 和 Render，搜索仍走免费通道。只有 AGENTSEARCH_MODE=paid，或者配置钱包后使用 AGENTSEARCH_MODE=auto，才会启用付费搜索。保持未设置或设为 AGENTSEARCH_MODE=free，搜索继续免费。

1.3.4 及更早版本的行为不同，配置钱包也会让搜索付费。原文给出的更新命令是 npx -y @agentsearchhq/agentsearch-mcp@latest。

需要全文读取时，作者建议单独添加付费服务：

claude mcp add agentsearch-paid \
  --env AGENTSEARCH_WALLET_PRIVATE_KEY=0xYOUR_DEDICATED_WALLET_KEY \
  --env AGENTSEARCH_MAX_TOTAL_ATOMIC=50000 \
  -- npx -y @agentsearchhq/agentsearch-mcp

注意服务名要放在 --env 前面，否则 CLI 可能把名称误读为另一个环境变量值。

原文写明 Search 和 Extract 每次收费 $0.005，没有给出 Render 的具体价格。支付入口支持 Base 上的 x402 或 Tempo 上的 MPP，但这里的 MCP 服务使用 Base 上的 USDC，通过 x402 支付，不需要 ETH 支付 gas。作者建议使用只存少量 USDC 的专用钱包。

AGENTSEARCH_MAX_TOTAL_ATOMIC 限制单次服务会话总支出，1000000 对应 $1.00，默认也是 $1.00；示例中的 50000 对应 $0.05，必须填写整数。AGENTSEARCH_MAX_PER_CALL_ATOMIC 限制单次调用金额，且只能调低。达到限额后，工具返回 Session spend cap reached ... Nothing was signed.。

会话限额会在服务重启后重置，不能把它当作长期预算。

还有一个容易漏掉的前提：stdio 服务会继承启动 claude 的 shell 环境。全局导出钱包私钥后，原本没单独配密钥的服务也可能获得支付能力。团队配置应使用 ${AGENTSEARCH_WALLET_PRIVATE_KEY} 引用，真实私钥留在 shell；${AGENTSEARCH_MAX_TOTAL_ATOMIC:-50000} 则可提供默认限额。

首次连接失败，可能只是 npx 下载超过启动超时，可重试列表查询，或用 MCP_TIMEOUT=60000 claude 启动。单独运行 npx -y @agentsearchhq/agentsearch-mcp，健康服务会向 stderr 输出 listening on stdio 并等待输入。原生 Windows 若不能直接启动 npx，可使用 claude mcp add agentsearch -- cmd /c npx -y @agentsearchhq/agentsearch-mcp；WSL 沿用 Linux 命令。

我的判断

这套方案适合先给 AI 编程补上「查资料」能力。无需申请 API key，项目配置可以共享，搜索与付费读取也有明确分工，试用成本确实低。

但作者实测的是接入和收费行为，没有提供搜索质量、响应延迟、中文资料覆盖或服务稳定性的对照数据。它比其他搜索工具更好用，目前只能算未被证明的判断。原文也没有建立「Claude Code 在所有配置下都无法联网」的结论，能确认的是这条 MCP 接入路径可用。

与手动打开官方文档相比，优势是省去搜索、复制资料、补充仓库上下文的往返；代价是摘要可能不完整，找到迁移指南后仍需读取相关章节。与自行接搜索 API 相比，它减少了初始接入步骤，但免费容量受 IP 和共享额度约束，付费又引入钱包管理，未必适合直接作为团队自动化的稳定依赖。

网页还可能夹带诱导 AI 行动的文字。原文提醒保留文件修改和命令执行的权限提示，这一点合理：搜索工具获准读取资料，不等于网页内容有权决定下一步操作。

能拿来做什么

• 先在个人项目使用免费搜索，明确要求查找官方资料，并对照 package.json 或具体源码文件输出影响，避免只得到一段泛泛介绍。
• 团队采用 --scope project 共享配置，成员批准后通过 /mcp 验证工具；排错时检查同名服务覆盖和启动 shell 的 PATH。
• 摘要不足时再配置 Extract；页面依赖 JavaScript 展示正文时再用 Render。付费服务使用专用钱包和限额，并检查继承的环境变量。
• 把联网结论当作待核对的开发输入，要求附上文档地址和对应代码位置，再决定是否升级依赖或修改实现。