用 Apify MCP Server 让 Agent 调用数千个采集器并自己付钱

官方明确推荐托管形态：https://mcp.apify.com，走 Streamable HTTP，支持 OAuth，很多客户端只要填一个 URL 就能连上。本地形态是 npm 包 @apify/actors-mcp-server，由客户端以 stdio 子进程拉起，靠 APIFY_TOKEN 环境变量鉴权。两者能力并不等价——托管端支持「对 Actor 结果做输出 schema 推断」这类结构化能力，本地 stdio 模式没有。如果你的客户端支持 OAuth 远程 MCP，直接用托管端点即可。

# 形态 A：托管（推荐）
https://mcp.apify.com                 # OAuth，客户端填 URL 即可
https://mcp.apify.com?payment=skyfire # 走 Skyfire 智能体付费

# 形态 B：本地 stdio
APIFY_TOKEN="apify_api_xxxx" npx @apify/actors-mcp-server

# 显式声明工具集（生产推荐，避免工具数量膨胀）
npx @apify/actors-mcp-server --tools actors,docs,apify/rag-web-browser

Apify MCP Server 兼容任何遵循 MCP 规范的客户端，官方测试过的包括 Claude Code、Claude.ai / Claude Desktop、Cursor、VS Code 等，但各家对「动态工具发现」的支持程度不一。托管形态在支持 OAuth 的客户端里最省事；若客户端不支持 OAuth，就在请求头里带 Authorization: Bearer <token>。本地形态则是在客户端的 MCP 配置里写命令加环境变量。接入完成后建议先做一次连通性验证：让客户端列出当前可用工具，确认能看到 actors 与 docs 相关工具，再开始跑实际任务。若工具列表为空，通常是鉴权没生效或传输方式选错，而不是 Actor 本身出了问题。

// Claude Desktop 的 claude_desktop_config.json（本地 stdio 版）
{
  "mcpServers": {
    "apify": {
      "command": "npx",
      "args": ["-y", "@apify/actors-mcp-server"],
      "env": { "APIFY_TOKEN": "apify_api_xxxxxxxx" }
    }
  }
}

# 命令行客户端（托管 + Bearer）
# 在客户端里把 URL 填成 https://mcp.apify.com，并配置
# Authorization: Bearer apify_api_xxxxxxxx

这是官方推荐的标准作业流，也是你要写进 Agent 提示词里的心智模型：先用 search-actors 在 Apify Store 里找合适的采集器；再用 fetch-actor-details 拿到它的输入 schema、文档、计费方式与输出 schema；确认无误后用 call-actor 启动任务；最后用 get-dataset-items 取结构化结果。关键在于中间那步——不看输入 schema 就调用，几乎必然参数错。

1) search-actors       按「抓 Google 地图上的商家信息」这类描述找 Actor
2) fetch-actor-details 读它的 input schema / 文档 / 计费 / 输出 schema
3) call-actor          按 schema 构造参数并启动
4) get-dataset-items   按 datasetId 取回结构化结果（可过滤、可分页）

# 排查与收尾的辅助工具
get-actor-run          查看某次运行状态
get-actor-log          看运行日志定位失败原因
get-key-value-store-record  读 kv 记录
abort-actor-run        中止一个仍在跑的任务
search-apify-docs / fetch-apify-docs   查官方开发文档

默认配置里已经带上了 apify/rag-web-browser 与 apify/web-fetch 两个实用 Actor。前者会搜索网页、抓取排名靠前的若干 URL 并返回正文，非常适合给 RAG 或调研类 Agent 当入口；后者抓取任意 URL 并以 Markdown、纯文本、HTML 或链接形式返回，还带 JavaScript 渲染与反爬处理。想让 Agent 回答「最近发生了什么」这类问题时，先走 rag-web-browser 通常比自己拼 search + fetch 更省事。如果你用的是本地 stdio 模式，默认工具集会略有差异，官方更建议用参数显式声明需要的工具集，而不是让它把全部采集器动态展开成工具——工具数量越少，模型选错的概率越低，冷启动也更快。

# 默认工具集（本地 stdio 等价写法）
--tools actors,docs,apify/rag-web-browser

# 典型对话（给 Agent 的自然语言指令）
用 rag-web-browser 检索「2026 MCP 规范变更」，
抓前 5 个结果，总结成要点并标注来源链接。

# 另一个常见用法：地图线索
找一个能抓 Google 地图商家信息的 Actor，
提取某城市咖啡馆的名称、地址、评分与电话。

这是一个容易踩的设计：call-actor 的返回并不内嵌全部输出条目，而是给运行元数据、存储 ID（如 datasetId）、一段摘要和一个 nextStep 提示。Agent 需要再用 get-dataset-items 按需取回结构化结果，可以过滤也可以分页。这个设计对上下文很友好——一次采集几千条数据也不会把模型的窗口撑爆，你要做的是教会 Agent「先取一小批看结构，再决定要不要继续翻页」。

call-actor 返回大致形态：
{
  "runId": "...",
  "datasetId": "...",
  "summary": "已采集 1200 条",
  "nextStep": "用 get-dataset-items 取回结果"
}

# 给 Agent 的分页指令范式
先取 20 条看字段结构，确认有 name / address / rating 后，
再按每次 100 条翻页，全部写进本地 CSV，不要一次性塞进对话。

还有一层容错上的好处：采集任务跑在 Apify 云端，本地断网或客户端重启都不会中断任务本身，你随时可以用 runId 回去取结果。对 Agent 来说，这意味着「发起长任务、稍后再取」这种异步模式天然成立，不必把整个等待过程耗在一次对话里。

跑 Actor 是要花钱的，官方支持三条路径：最常规是用你自己的 Apify Token 走账户额度；其次是智能体付费——买 AGI 代币让 Agent 自己付（官方推荐），或用 x402 按请求直接支付（仅支持按事件计费的 Actor）；还有一条是 Skyfire，在 URL 上加 ?payment=skyfire 即可。无论走哪条，都建议给 Agent 设预算上限与调用审计。

# 三条付费路径
1) APIFY_TOKEN            走你自己账户的 Apify 额度
2) AGI 代币 / x402        让 Agent 自己按次付费（x402 仅支持 Pay Per Event Actor）
3) Skyfire                https://mcp.apify.com?payment=skyfire

# 关闭遥测（官方 README 有关闭章节）
APIFY_MCP_TELEMETRY=0    # 具体变量名以官方 README 当前版本为准