BillionVerify LogoBillionVerify
AI 指南

MCP Server

将 BillionVerify 的 OAuth 保护 MCP Server 连接到 ChatGPT 和其他兼容 MCP 的 AI 客户端。

模型上下文协议（MCP）是一项开放标准，允许 AI 客户端通过统一接口调用外部工具。BillionVerify 提供了一个托管式 MCP Server，可通过 Streamable HTTP 提供邮箱验证、账户报告、结果下载和 Webhook 管理能力。

MCP Server 版本2.1.0
服务端点https://mcp.billionverify.com/mcp
认证模型OAuth 2.1 + Bearer access token
Protected Resource Metadatahttps://mcp.billionverify.com/.well-known/oauth-protected-resource
可用工具11
可用资源3

重要

BillionVerify MCP Server 不支持 ?api_key=... query 参数、内嵌 API key 的 resource URI，也不支持 tool 参数中的 api_key。

如果你以前使用 curl --stdio "https://mcp.billionverify.com/mcp?api_key=..."，这条接入方式现在已经不再支持。请改用支持 OAuth 的远程 MCP 客户端。如果你的客户端只支持本地 stdio + API key，请改用 BillionVerify REST API，而不是 MCP。

你可以做什么

  • 验证单个邮箱地址
  • 在一次批量请求中验证最多 50 个邮箱
  • 查询账户积分余额
  • 跟踪异步验证任务状态
  • 为已完成任务生成筛选后的下载链接
  • 查看验证历史和汇总统计
  • 创建、列出和删除生命周期通知 Webhook

认证如何工作

BillionVerify MCP 使用标准的远程 OAuth 流程：

  1. 你的 MCP 客户端会从 https://mcp.billionverify.com/.well-known/oauth-protected-resource 发现 protected resource metadata。
  2. 客户端会自动跟随声明的 authorization server metadata。
  3. 你使用 BillionVerify 账户登录，并批准所请求的 scopes。
  4. 随后客户端会携带 Authorization: Bearer <access_token> 调用 https://mcp.billionverify.com/mcp。

可用 Scopes

Scope用途
billionverify.read读取余额、任务状态、历史、统计和下载链接
billionverify.verify执行邮箱验证工具
billionverify.webhooks创建、列出和删除 Webhook

从 ChatGPT 连接

如果你要从 ChatGPT 连接 BillionVerify，请使用下面这个远程 MCP Server URL：

https://mcp.billionverify.com/mcp

ChatGPT 会自动发现 OAuth 保护资源元数据，跳转到 BillionVerify 的登录与授权页面，然后使用 access token 调用 MCP Server。

连接完成后，你可以直接提出下面这类请求：

  • Verify jane@company.com
  • Check my current BillionVerify credit balance
  • Show my recent verification history
  • Get a download link for only valid emails from job 36f68e67-ddcb-441a-a407-22f826e72443

从其他 MCP 客户端连接

任何支持以下能力的 MCP 客户端都可以连接到同一个端点：

  • 通过 Streamable HTTP 的远程 MCP
  • OAuth-protected resources
  • 标准 Bearer token 认证

连接地址仍然是：

https://mcp.billionverify.com/mcp

请使用你的客户端自带的远程 MCP 配置流程，并填写上面的 URL。不要再用 curl --stdio 包一层，也不要把 API key 拼到 URL 上。

什么时候应该改用 REST API

以下场景建议使用 BillionVerify REST API，而不是 MCP：

  • 你的客户端只支持本地 stdio MCP Server
  • 你的集成依赖 API key，而不是 OAuth
  • 你在构建没有 MCP 客户端参与的 backend-to-backend 自动化

API key 仍然适用于 BillionVerify REST API，只是它不再属于 MCP 的认证模型。

可用工具

工具Scope描述
health_checknone检查 MCP Server 是否可达且健康
verify_single_emailbillionverify.verify验证单个邮箱地址
verify_batch_emailsbillionverify.verify验证最多 50 个邮箱地址
get_account_balancebillionverify.read获取当前账户积分余额和使用摘要
get_task_statusbillionverify.read查询异步验证任务状态
get_download_urlbillionverify.read为已完成任务生成筛选后的下载链接
get_verification_historybillionverify.read获取当前认证账户的验证历史
get_verification_statsbillionverify.read获取汇总验证统计
create_webhookbillionverify.webhooks创建验证 Webhook
list_webhooksbillionverify.webhooks列出已配置的 Webhook
delete_webhookbillionverify.webhooks按 ID 删除 Webhook

可用资源

Resource URIScope描述
billionverify://account/infobillionverify.read账户级积分与使用摘要
billionverify://history/summarybillionverify.read最近验证历史摘要
billionverify://stats/verificationbillionverify.read汇总验证统计

示例提示词

单邮箱验证

Verify john@google.com

批量验证

Verify these emails in one request: john@google.com, test@mailinator.com, support@microsoft.com

账户余额

How many BillionVerify credits do I have left?

验证历史

Show my 20 most recent verification jobs

下载筛选结果

Get a download link for only valid emails from job job-123

Webhook 管理

Create a webhook for file.completed and file.failed events at https://example.com/webhooks/billionverify

MCP 返回示例

verify_single_email

{
  "email": "user@example.com",
  "status": "valid",
  "score": 1,
  "is_deliverable": true,
  "is_disposable": false,
  "is_catchall": false,
  "is_role": false,
  "is_free": true,
  "domain": "example.com",
  "mx_records": ["has_mx_records"],
  "smtp_check": true,
  "response_time": 2,
  "credits_used": 1
}

get_task_status

{
  "job_id": "job-uuid-xxxxx",
  "status": "completed",
  "progress": 100,
  "total_emails": 1000,
  "processed_emails": 1000,
  "valid_count": 850,
  "invalid_count": 100
}

get_account_balance

{
  "account_id": "acc_xxx",
  "credits_balance": 842740,
  "credits_consumed": 157260,
  "credits_added": 1000000,
  "last_updated": "2026-02-05T04:51:35Z"
}

故障排查

我收到了 401、OAuth 授权提示，或者 mcp/www_authenticate

这通常意味着客户端还没有完成 OAuth 授权、access token 已过期，或者缺少所需 scope。请重新连接 MCP Server，并批准所请求的 scopes。

我的客户端只支持 curl --stdio 或本地 JSON + API key 配置

这类客户端与 BillionVerify 当前的远程 MCP 认证模型不兼容。请改用 BillionVerify REST API。

我以前用 ?api_key=... 可以连，现在不行了

这条 legacy 接入方式已经从 MCP surface 中移除。请切换到支持 OAuth 的 MCP 客户端，并直接连接远程端点。

积分如何计费？

  • 有效邮箱：1 积分
  • 无效邮箱：0 积分
  • 未知邮箱：0 积分

你可以通过 get_account_balance 查看剩余余额。

FAQ

MCP Server 支持 API key 吗？

不支持。远程 MCP Server 需要 OAuth access token。开发者 API key 适用于 REST API，不适用于 MCP 连接初始化。

支持哪些客户端？

任何支持基于 Streamable HTTP 的远程 MCP 和 OAuth-protected resources 的客户端都可以连接，ChatGPT 就是其中之一。如果客户端不支持远程 OAuth MCP，请改用 REST API。

需要安装 npm 包吗？

不需要。这是一个托管式远程 MCP Server，你只需要直接连接 https://mcp.billionverify.com/mcp。

可以通过 MCP 获取历史和统计吗？

可以。使用 get_verification_history、get_verification_stats，或者对应的只读 resources。

下一步

AI SDK Integration

Build custom AI applications with email verification

CLI Tools

Use email verification in terminal

API Reference

Use the REST API for API-key-based integrations

AI Guides

Email checker for AI agents. MCP Server, Claude Code, AI SDKs integration. Automated email verification.

AI SDKs

Email checker integration with AI SDKs. Anthropic, OpenAI, LangChain, Vercel AI SDK guides.

On this page

你可以做什么认证如何工作可用 Scopes从 ChatGPT 连接从其他 MCP 客户端连接什么时候应该改用 REST API可用工具可用资源示例提示词单邮箱验证批量验证账户余额验证历史下载筛选结果Webhook 管理MCP 返回示例verify_single_emailget_task_statusget_account_balance故障排查我收到了 401、OAuth 授权提示，或者 mcp/www_authenticate我的客户端只支持 curl --stdio 或本地 JSON + API key 配置我以前用 ?api_key=... 可以连，现在不行了积分如何计费？FAQMCP Server 支持 API key 吗？支持哪些客户端？需要安装 npm 包吗？可以通过 MCP 获取历史和统计吗？下一步