MCP Server

Model Context Protocol（MCP）は、AI クライアントが共通インターフェースを通じて外部ツールを呼び出せるようにするオープン標準です。BillionVerify は、メール検証、アカウントレポート、結果ダウンロード、Webhook 管理のためのホスト型 MCP サーバーを Streamable HTTP で提供しています。

重要

BillionVerify の MCP サーバーは、?api_key=... のクエリパラメータ、API キーを埋め込んだリソース URI、api_key のツール引数を サポートしていません。

以前 curl --stdio "https://mcp.billionverify.com/mcp?api_key=..." を使っていた場合、その方式はもう使えません。OAuth に対応したリモート MCP クライアントを使ってください。クライアントがローカル stdio + API キーにしか対応していない場合は、MCP ではなく BillionVerify REST API を利用してください。

できること

• 単一のメールアドレスを検証する
• 1 回のバッチ呼び出しで最大 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 アカウントでサインインし、要求されたスコープを承認します。
4. その後、クライアントは Authorization: Bearer <access_token> を付けて https://mcp.billionverify.com/mcp を呼び出します。

利用可能なスコープ

ChatGPT から接続する

ChatGPT から BillionVerify を接続する場合は、次のリモート MCP サーバー URL を使います。

https://mcp.billionverify.com/mcp

ChatGPT は protected resource metadata を検出し、BillionVerify のサインインと同意画面へリダイレクトし、その後アクセストークン付きで MCP サーバーを呼び出します。

接続後は、次のような依頼ができます。

• 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 トークン認証

同じエンドポイントに接続できます。

https://mcp.billionverify.com/mcp

クライアントのリモート MCP 設定フローで上記 URL を指定してください。curl --stdio でラップしたり、URL に API キーを付けたりしないでください。

REST API を使うべきケース

次のような場合は、MCP ではなく BillionVerify REST API を使ってください。

• クライアントがローカル stdio MCP サーバーしかサポートしない
• 連携が OAuth ではなく API キーに依存している
• MCP クライアントなしのバックエンド間自動化を構築している

API キーは BillionVerify REST API では引き続き利用できます。ただし、MCP の認証モデルには含まれません。

利用可能なツール

利用可能なリソース

例のプロンプト

単一メールの検証

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 認可をまだ完了していない、アクセストークンの期限が切れている、または必要なスコープが不足していることを意味します。MCP サーバーを再接続し、要求されたスコープを承認してください。

クライアントが curl --stdio または API キー付きローカル JSON 設定しかサポートしていない

そのクライアントは、BillionVerify の現在のリモート MCP 認証モデルに対応していません。代わりに BillionVerify REST API を使ってください。

以前は ?api_key=... で接続できたのに今は動かない

そのレガシーフローは MCP から削除されました。OAuth 対応の MCP クライアントに切り替え、リモートエンドポイントへ直接接続してください。

クレジットはどう計算されますか？

• 有効なメール: 1 クレジット
• 無効なメール: 0 クレジット
• 不明なメール: 0 クレジット

残高は get_account_balance で確認できます。

FAQ

MCP サーバーは API キーをサポートしていますか？

いいえ。リモート MCP サーバーは OAuth のアクセストークンを必要とします。開発者向け API キーは REST API 用であり、MCP 接続の初期化には使いません。

どのクライアントが対応していますか？

Streamable HTTP 上のリモート MCP と OAuth-protected resources に対応したクライアントであれば接続できます。ChatGPT はその一例です。リモート OAuth MCP に未対応のクライアントでは REST API を使ってください。

npm パッケージをインストールする必要がありますか？

いいえ。これはホスト型のリモート MCP サーバーです。https://mcp.billionverify.com/mcp に直接接続します。

履歴や統計も MCP から取得できますか？

はい。get_verification_history、get_verification_stats、または対応する読み取り専用リソースを利用してください。

次のステップ