MCP 服务

Zelnum 提供公共 MCP 服务，地址 https://mcp.zelnum.com/mcp。任何支持 MCP 的 客户端 —— Claude、Cursor、IDE 里的 Agent —— 都能列出产品、询价、发起检测并读取 结果，无需写任何对接代码。所有客户共用这一个地址：你用自己账号的 API Key 连接，费用也记在你自己账号上。

接入点

配置项	值
地址	https://mcp.zelnum.com/mcp
传输方式	Streamable HTTP
凭据	Authorization: Bearer YOUR_KEY_HERE

凭据就是你调用 REST 接口用的那把 API Key，在控制台 API 中心 创建、重新生成 和删除，详见认证。

连接客户端

三步完成，全程无需安装。

1. 创建 Key。 在控制台 API 中心 建一把 API Key —— 就是你调 REST 接口用的 那把，详见认证。

2. 添加服务。 Cursor 以及其它读取标准 mcpServers 配置的客户端，可以直接用 下面这段：

{
  "mcpServers": {
    "zelnum": {
      "url": "https://mcp.zelnum.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY_HERE"
      }
    }
  }
}

Claude 在自定义连接器（custom connector）对话框里填同样两个值：地址，以及一条 携带你 Key 的 Authorization 请求头。

3. 验证连接。 让 Agent 说说它现在能查哪些实时产品。连得通的话，它会调用 list_products 回答 —— 这个工具只读且免费，所以这次自检不花一分钱。若返回的是 401，说明 Key 缺失、已吊销，或平台不接受。

可用工具

工具	作用	是否计费
list_products	当前产品目录，含 ID、slug 与系列。只读。	否
get_balance	当前连接所鉴权账号的余额。只读。	否
quote_realtime_check	单次检测的权威报价。Agent 唯一可信的价格来源。	免费
check_realtime	对一个号码/邮箱发起实时检测，最多 10 个产品。	是
create_bulk_task	以内联数组提交异步批量任务。	是
get_task_status	查询批量任务的进度与计费计数。	否
get_task_result	已完成任务的结果元数据与鉴权下载链接。	否

你可以这样对 AI 说

上面那张表是 Agent 调用的工具，下面这些是你要打的字。每一句都对应一个已经存在的 工具，没有任何”特殊措辞”。

这样说	会发生什么
现在实时能查哪些产品？	调用 list_products，把可用的产品 ID 报给你。免费。
我账户余额还有多少？	调用 get_balance，读取你连接所用 Key 的余额。免费。
查一下 +14155550123 的 WhatsApp 要多少钱？	调用 quote_realtime_check 报价。免费，不扣款。
好，就按这个价格查。	调用 check_realtime，按报价中的产品执行，扣掉报价金额。
把这 200 个号码查一遍 WhatsApp，完了告诉我。	调用 create_bulk_task 提交，随后轮询 get_task_status 汇报进度。
那个任务好了吗？把下载链接给我。	调用 get_task_result，返回鉴权下载链接。

两个值得养成的好习惯：

• 先问价。 计费类工具在扣款前一定会先给报价，所以”这要多少钱”永远免费。真正 动钱的只有确认那一步。
• 号码不是 E.164 时，报国家。 +14155550123 自带国家；0812345678 没有，而 网关拒绝猜。

确认计费

计费类工具第一次调用不会扣款。不带 confirmed 调用时，它返回的是确认载荷 —— 产品、数量与预估费用 —— 以及一个为该次输入签名的 quote_token。确认时用 完全相同的参数再调一次，并带上：

1. confirmed 置为 true
2. 上一步返回的 quote_token
3. quoted_total，与展示给你的金额完全一致
4. 相同的号码/邮箱、产品与 country

Agent 不会自己生成幂等键：网关从签名报价派生，所以同一份已批准的报价在重试、 重连、网关重启之后仍是同一个键。金额变了就必须重新报价。超时导致结果未知时， 原样重发同一次调用，不要改参数。

绝不允许静默扣款

Agent 必须先展示预估费用并取得明确同意，才能置上 confirmed 标记。报价五分钟 过期；若期间价格快照已变动，该报价会被拒绝，而不是按新价格扣款。

号码格式

号码规则与 REST 契约完全一致，Agent 侧校验通过的就是接口会接受的：

• 不传 country —— 号码必须是带 + 的 E.164 格式。
• 传 country —— 需为大写两位 ISO 国家码，此时号码可以是本地格式，也可以是 E.164。
• 系统绝不会从 0812345678 这类有歧义的本地号码反推国家（多个国家都符合）。 只有在号码本身就是完整 E.164 时才可省略 country。
• 手机号产品的批量任务必须显式传 country（见国家代码列表）。

资金护栏

Agent 与你的余额之间有四道护栏：

1. 签名报价。 平台读取实时价格并返回加密报价，把账号、精确输入、产品与价格 快照绑定在一起。输入被改动、报价过期、价格变动，都会在计费前被拒绝。
2. 确定性幂等。 幂等键来自签名报价而非模型，因此任何措辞都无法把一次批准变成 两次扣款。
3. 按 Key 限额。 日累计花费上限与余额下限按 API Key 独立生效，且每次预占都在 调用上游之前串行化，并发 Agent 无法绕过。
4. 失败即拒。 余额读不到或返回格式异常时，计费类调用一律拒绝，而不是无保护地 执行。

错误与限制

• 缺少凭据或凭据格式错误，在请求到达平台之前就以 HTTP 401 拒绝。
• 平台不接受的 Key 会作为工具错误返回，并携带上游状态码与响应体，Agent 会如实 报告而不是盲目重试。
• 限流、错误码与结果下载的行为与 REST 完全一致 —— 网关不会多出一套契约。详见 限流与错误码。

下一步

• 认证 —— 创建你用来连接的 Key。
• 实时检测 —— check_realtime 背后的接口。
• 批量流程 —— create_bulk_task 背后的异步链路。
• 错误码 —— 平台会返回的全部错误码。