MCP Server

Model Context Protocol (MCP) is an open standard that lets AI clients call external tools through a shared interface. BillionVerify exposes a remote MCP server for email verification, account reporting, result downloads, and webhook management over Streamable HTTP.

Important

The BillionVerify MCP server does not support ?api_key=... query parameters, resource URIs with embedded API keys, or tool-level api_key arguments.

If you previously used curl --stdio "https://mcp.billionverify.com/mcp?api_key=...", that flow is no longer supported. Use an OAuth-capable remote MCP client instead. If your client only supports local stdio + API keys, use the BillionVerify REST API rather than MCP.

What You Can Do

• Verify a single email address
• Verify up to 50 email addresses in one batch call
• Check account credit balance
• Track asynchronous verification job status
• Generate filtered download links for completed verification jobs
• Read verification history and account-level verification stats
• Create, list, and delete webhooks for lifecycle notifications

How Authentication Works

BillionVerify MCP uses a standard remote OAuth flow:

1. Your MCP client discovers the protected resource metadata from https://mcp.billionverify.com/.well-known/oauth-protected-resource.
2. The client follows the declared authorization server metadata automatically.
3. You sign in with your BillionVerify account and approve the requested scopes.
4. The client calls https://mcp.billionverify.com/mcp with Authorization: Bearer <access_token>.

Available Scopes

Connect From ChatGPT

If you are connecting BillionVerify from ChatGPT, use the remote MCP server URL:

https://mcp.billionverify.com/mcp

ChatGPT will discover the OAuth-protected resource metadata, redirect you to BillionVerify sign-in and consent, and then call the MCP server with an access token.

After the connection is approved, you can ask for things like:

• 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

Connect From Other MCP Clients

Any MCP client that supports:

• remote MCP over Streamable HTTP
• OAuth-protected resources
• standard Bearer token authorization

can connect to the same endpoint:

https://mcp.billionverify.com/mcp

Use your client's remote MCP configuration flow and provide the endpoint above. Do not wrap the server behind curl --stdio, and do not append an API key in the URL.

When To Use REST API Instead

Use the BillionVerify REST API instead of MCP if:

• your client only supports local stdio MCP servers
• your integration depends on API keys instead of OAuth
• you are building a backend-to-backend automation without an MCP client

API keys still exist for the BillionVerify REST API. They are just not part of the MCP authentication model anymore.

Available Tools

Available Resources

Example Prompts

Single Email Verification

Verify john@google.com

Batch Verification

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

Account Balance

How many BillionVerify credits do I have left?

Verification History

Show my 20 most recent verification jobs

Download Filtered Results

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

Webhook Management

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

Example MCP Responses

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"
}

Troubleshooting

I get 401, an OAuth prompt, or mcp/www_authenticate

This usually means the client has not completed OAuth authorization yet, the access token expired, or the client is missing the required scope. Reconnect the MCP server and approve the requested scopes.

My client only supports curl --stdio or local JSON config with API keys

That client is not compatible with BillionVerify's current remote MCP auth model. Use the BillionVerify REST API instead of MCP.

I used to connect with ?api_key=... and it stopped working

That legacy flow has been removed from the MCP surface. Switch to an OAuth-capable MCP client and connect with the remote endpoint directly.

How do credits work?

• Valid email: 1 credit
• Invalid email: 0 credits
• Unknown email: 0 credits

Use get_account_balance to inspect your remaining balance.

FAQ

Does the MCP server support API keys?

No. The remote MCP server requires OAuth access tokens. Developer API keys are for the REST API, not for MCP connection bootstrap.

Which clients are supported?

Any client that supports remote MCP over Streamable HTTP and OAuth-protected resources can connect. ChatGPT is one example. For clients without remote OAuth MCP support, use the REST API instead.

Do I need to install an npm package?

No. This is a hosted remote MCP server. You connect to https://mcp.billionverify.com/mcp directly.

Can I fetch history and stats from MCP?

Yes. Use get_verification_history, get_verification_stats, or the corresponding read-only resources.

Next Steps