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 Metadata	`https://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 流程：

你的 MCP 客戶端會從 https://mcp.billionverify.com/.well-known/oauth-protected-resource 發現 protected resource metadata。
客戶端會自動跟隨宣告的 authorization server metadata。
你使用 BillionVerify 帳戶登入，並批准所要求的 scopes。
接著客戶端會帶著 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_check`	none	檢查 MCP Server 是否可達且健康
`verify_single_email`	`billionverify.verify`	驗證單一郵箱地址
`verify_batch_emails`	`billionverify.verify`	驗證最多 50 個郵箱地址
`get_account_balance`	`billionverify.read`	取得目前帳戶積分餘額與使用摘要
`get_task_status`	`billionverify.read`	查詢非同步驗證任務狀態
`get_download_url`	`billionverify.read`	為已完成任務產生篩選後的下載連結
`get_verification_history`	`billionverify.read`	取得目前認證帳戶的驗證歷史
`get_verification_stats`	`billionverify.read`	取得彙總驗證統計
`create_webhook`	`billionverify.webhooks`	建立驗證 Webhook
`list_webhooks`	`billionverify.webhooks`	列出已設定的 Webhook
`delete_webhook`	`billionverify.webhooks`	依 ID 刪除 Webhook

可用資源

Resource URI	Scope	描述
`billionverify://account/info`	`billionverify.read`	帳戶層級積分與使用摘要
`billionverify://history/summary`	`billionverify.read`	最近驗證歷史摘要
`billionverify://stats/verification`	`billionverify.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"
}