Skip to main content
这页介绍的是 DataHub 通用 MCP：它先帮助 Agent 发现合适的 Data App，再读取 App 的实时契约并运行。它和“先选择一个指定 App 再连接”的教程使用同一套 DataHub 能力，区别只是选 App 的时间不同。
Data App 的数量、名称、发布者、价格和输入输出会持续更新；MCP 协议工具则相对稳定。因此，本页重点说明工具契约和通用流程，不把某次市场目录当成长期清单。

​
两层能力

长期集成某个固定 App 时，优先记录它的 app_id（形如 app_<hex>）；namespace/app_name 也可以引用 App，但发布者或应用改名后会失效。

​
七个 MCP 工具

​
search_data_apps：搜索目录

用业务关键词发现 Data App。query 支持中英文关键词，加上平台名可以缩小范围（例如“temu 评论”）；留空可分页查看当前可见目录。 结果卡片会给出 app_id、名称、简介、运行模式（sync / async）、输入输出提示、起始价格、可见范围和是否接受运行（accepting_runs）。卡片不含完整价格表，计费明细在详情里。先搜索和比较，未确认前不要直接运行。

​
get_data_app_details：读取完整契约

在运行前调用。参数 app 传入 app_id 或 <namespace>/<app_name> 后，可取得：
  • input_schema：本次运行必须满足的标准 JSON Schema。
  • output_schema：可能返回的字段。
  • knowledge：能力边界、预期延迟和注意事项。
  • pricing：计费说明，逐个计费事件列出单价。
  • examples：可作为起点的输入示例。
最稳的方式是从 examples 复制一份 input 再按需求调整。不要从页面标题、聊天描述或旧任务中猜测字段名。

​
run_data_app：发起运行

传入 app、满足 input_schema 的 input，必要时设置 max_records 控制最大结果数。输入不符合契约时会立即返回 [invalid-input] 并指出字段问题。 返回的是运行对象，按 state 和 next_step 行动：
  • 终态（SUCCEEDED / PARTIALLY_SUCCEEDED / FAILED / CANCELLED）：records 内联前 50 条结果，pagination.total 是总条数；带 handoff 时按它取剩余部分。PARTIALLY_SUCCEEDED 的 partial 为 true，记录可用；FAILED 在 error 中说明原因。
  • 进行中（QUEUED / RUNNING）：还没有数据，费用也不完整。用 get_run_status(run_id, wait_seconds=60) 等待，再用 get_run_result 读取；cancel_run 可以中止并保留已产出的记录。
拿到哪一种取决于 wait_seconds：秒级完成的 App（sync）传 wait_seconds=60 即可在这一次调用里直接拿到结果；长时间运行的 App（async）保持 0。同时处理多个目标时，先用 wait_seconds=0 连续发起全部运行，再统一等待，运行会在平台上并行执行。 运行对象的其他字段：run_id（后续每个工具都用它）、progress（done / total / status_text）、usage 和 billing（终态后才完整）。 三类错误不可重试，应把原因转告用户而不是重复调用：

​
get_run_status：查询运行状态

传入 run_id 查询进度、失败信息、用量与费用，但不读取数据。用 wait_seconds（0-60）长轮询：平台会保持连接直到运行到达终态或时间用尽，仍未到终态就原样再调一次。建议一次等待 60 秒，不要用 0 高频轮询。 常见状态为：QUEUED、RUNNING、SUCCEEDED、PARTIALLY_SUCCEEDED、FAILED、CANCELLED；另有较少见的 PENDING（已受理、尚未排队）和 EXPIRED（超时过期，视同终态）。失败时重点查看 error.code、error.category、error.message 和 error.retryable。状态为 SUCCEEDED 或 PARTIALLY_SUCCEEDED 后再用 get_run_result 读取结果。

​
get_run_result：读取结果

单次最多读取 50 条。可通过 offset 分页，通过 fields 指定逗号分隔的字段子集，例如 title,price,url，避免把不需要的大量字段带入对话。 pagination.total 是总条数；partial 为 true 表示运行部分成功或被取消，这些记录有效且已计费。运行进行中调用只会读到截至当前已产出的部分，total 会持续增长，完整结果要等终态。 当响应出现 handoff，表示结果较大或不适合继续在对话中翻页。它会说明两种选择（继续翻页，或按给出的 SDK / REST 命令导出文件）以及各自适用的场景；数据量大且用户没有指定时，先询问再继续，不要让 Agent 反复搬运全部 JSON。

​
cancel_run：取消运行

传入 run_id 可取消排队或正在执行的任务。排队中的立即停止，执行中的通常在数秒内协作停止；已成功产出的部分结果会保留（partial 为 true），并可继续通过 get_run_result 读取。只按已产出的数据计费。取消后用 get_run_status 确认终态；对已经结束的运行调用会报错，没有副作用。

​
list_runs：列出我的运行

列出当前凭证所属账号名下的运行，按发起时间倒序、分页返回，只含元信息不含结果数据。归属按账号而不是按本次会话：从网页、SDK、API 或 MCP 发起的运行都会出现在这里。 典型用途：
  • 找回丢失的 run_id：会话中断后异步运行仍在平台上执行和计费，按 App 或时间范围缩小后用 get_run_status 继续。
  • 批量检查：按 status 筛出尚未到终态的运行。
  • 核对费用：按 App 或时间范围列出运行，看每一项的 billing。
返回 items[]（run_id / state / created_at / usage / billing 等）和 pagination，has_more 为 true 时增大 offset 继续翻页。

​
钉选 App 专用工具

在开放平台“MCP 连接”里勾选 App，或在连接地址上加 ?pin=<App 引用>（逗号分隔多个），这些 App 会以专用工具的形式挂在七个固定工具之前，工具名是引用的两段以 __ 相连（例如 carol__probe-b）。专用工具的参数就是该 App 的输入字段，外加与 run_data_app 相同的 max_records 和 wait_seconds；返回结构也与 run_data_app 完全一致，后续同样用 get_run_status / get_run_result / cancel_run 处理。 钉选是纯加法，七个固定工具始终可用。用两段式引用钉选的 App 在发布者改名后会失效，用 app_id 钉选不受影响。

​
标准工作流

​
同步与异步 App

两种模式返回的运行对象结构相同，判断依据只有 state，不必按模式写两套逻辑。异步任务只得到 run_id 不等于采集成功。必须确认终态，再读取结果；同一目标不要因为等待而重复提交任务。

​
费用与核对

每次运行返回的 billing 块记录了这一次按哪些事件、多少数量、什么单价收了多少钱，终态后为准；usage 块是客观用量（记录数、耗时）。Agent 侧核对费用用 list_runs 按 App 或时间范围列出运行即可。需要按日、按 App、按 Key 汇总，或查看账户累计消费，MCP 没有对应工具，请使用 REST API 或 SDK，见接口参考中的账单聚合与账户信息。 计费规则对所有接入方式一致：失败不计费，部分成功和取消只按已产出计费，取量由平台从入库数据派生。

​
Data App 的使用原则

Data App 是 DataHub 中具体的数据能力。它们会随市场更新，因此不维护静态目录；使用前直接用 search_data_apps 搜索，再用 get_data_app_details 确认当前的输入、输出、价格和边界即可。

​
连接与使用建议

DataHub MCP 的通用服务以 https://mcp-v2.bazhuayu.com 为基础，采用 Streamable HTTP 传输，支持 API Key 或 OAuth；连接配置和当前参数以 DataHub 开放平台生成的内容为准。它不同于「八爪鱼采集器 → MCP 服务」中的采集器 MCP，二者不要混用地址、认证和工具名。