01

什么是 MCP?

Model Context Protocol(模型上下文协议)是一种开放标准,让 AI 应用可以在对话中调用外部工具。连接后,你可以直接让助手检测一个号码或分析一批号码,而不需要单独编写 API 集成。

MCP 只是协议适配层,不是一套独立的检测系统。它与 REST API 使用相同的产品、余额、计费、速率限制、并发限制和结果语义。
02

认证方式

使用 REST API 完全相同的 API Key,并在 MCP 客户端配置中将其作为 Bearer Token 发送。

Authorization 请求头
Authorization: Bearer YOUR_API_KEY
妥善保管 API Key

只在你自己信任的客户端配置中添加 API Key,不要暴露在浏览器代码或公开提示词中。

03

服务器地址

将客户端指向官方 Streamable HTTP 地址即可,不需要在本地运行 MCP 进程。

MCP 接口地址http://localhost:14004/mcp

请求通过 Streamable HTTP 传输 JSON-RPC,并复用 REST 接口使用的 API Key 鉴权中间件。

04

连接你的客户端

选择客户端支持的配置格式,并将占位符替换为你的 API Key。

Claude Code

在终端中添加远程 MCP 服务。

claude mcp add --transport http tgvalidator https://tgvalidator.com/mcp --header "Authorization: Bearer YOUR_API_KEY"

Cursor / Claude Desktop

将服务配置添加到客户端的 MCP 配置文件中。

{
  "mcpServers": {
    "tgvalidator": {
      "url": "https://tgvalidator.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

其他 MCP 客户端

使用上面的地址和 Bearer 请求头,通过 Streamable HTTP 连接。

URL: https://tgvalidator.com/mcp
Authorization: Bearer YOUR_API_KEY
05

可用工具

工具范围由 API Key 所属的应用决定。如果需要发现有效的产品编码,请先调用 list_products。

list_products

列出当前 API Key 可用的产品、价格、计费倍数和返回字段。

无需参数
check_number

同步检测一个 E.164 手机号,registered 是主结果。

service_type · string · 必填
identifier · string · 必填
check_numbers

使用同一个 service_type 检测 1–100 个号码,并保持输入顺序。

service_type · string · 必填
identifiers · string[] · 必填 · 最多 100 个
get_balance

读取当前账户余额,不会产生扣费。

无需参数

提示词示例

连接后,可以用自然语言向助手提出请求:

  • 检查 +14155552671 是否注册了 Telegram。
  • 检查这 20 个号码,并汇总结果。
  • 运行这批检测前还剩多少余额?
06

错误处理

工具失败时会返回 isError=true,并继续使用 API 相同的 code、msg、data 响应契约。

工具错误示例
{
  "code": 42900,
  "msg": "rate limit exceeded",
  "data": null
}
40100

API Key 缺失或无效

检查 Bearer 请求头,并确认 API Key 仍处于启用状态。

40200

余额不足

检查余额或充值后再重试。

42900 / 42901

速率或并发限制

等待速率窗口或正在执行的检测结束后再重试。

40000 / 40002

产品或号码无效

使用 list_products 返回的产品,并提交 E.164 国际号码。

42200 / 50300

无法判定或临时服务失败

不要将号码归类为未注册,请稍后重试。

准备好连接你的 AI 助手了吗?

创建账号、复制 API Key,然后从你常用的 MCP 客户端开始检测。