MCP Server

Model Context Protocol (MCP) is an open protocol by Anthropic that enables AI models to securely interact with external tools and data sources. BillionVerify provides enterprise-grade email verification capabilities for AI agents through HTTP Streamable Transport, making integration incredibly simple.

Why AI Agents Need Email Verification

Modern AI agent use cases include:

• Claude Code needs to verify email addresses when processing user data
• OpenCode requires email validation in automated workflows
• Gemini CLI agents need quality assurance when handling registration data
• Codex generated code needs built-in email verification logic
• Custom AI Agents need to confirm contact authenticity when interacting with humans

BillionVerify MCP enables any AI agent to directly call enterprise-grade email verification services through the HTTP Streamable Transport standard - no complex configuration required.

Core Features

1. Single Email Real-time Verification

• Verify email format, domain, and MX records
• Optional SMTP connection check
• Disposable email detection
• Company vs free email identification
• Role-based email detection (support@, noreply@, etc.)
• Average response time < 2 seconds

2. Batch Email Verification

• Verify up to 50 emails at once
• Concurrent processing for efficiency
• Detailed results and statistics

3. Smart Caching System

• Valid emails cached for 7 days
• Invalid emails cached for 7 days
• Unknown status cached for 10 minutes
• Reduces unnecessary repeated verifications

4. Precise Credit Billing

• Valid email: 1 credit
• Invalid email: 0 credits (prevents waste)
• Unknown status: 0 credits (auto-retry)
• Real-time balance queries

Supported AI Clients

Quick Setup (HTTP Transport - Recommended)

The simplest way to integrate - no npm packages to install!

Step 1: Get API Key

Visit the BillionVerify Dashboard to create your API key.

Step 2: Configure Claude Desktop

Edit the configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "billionverify": {
      "command": "curl",
      "args": ["--stdio", "https://mcp.billionverify.com/mcp?api_key=YOUR_API_KEY"]
    }
  }
}

Replace YOUR_API_KEY with your actual API key, then restart Claude Desktop.

That's it! No npm install, no dependencies. curl is pre-installed on all systems. Claude now has email verification capabilities.

Step 3: Start Verifying

In your conversation, simply ask:

Please verify this email: user@example.com

Claude will automatically call BillionVerify and return detailed results.

Claude Code Setup

For Claude Code CLI, add the MCP server:

claude mcp add billionverify -- curl --stdio "https://mcp.billionverify.com/mcp?api_key=YOUR_API_KEY"

Or add to your ~/.claude.json:

{
  "mcpServers": {
    "billionverify": {
      "command": "curl",
      "args": ["--stdio", "https://mcp.billionverify.com/mcp?api_key=YOUR_API_KEY"]
    }
  }
}

OpenCode Setup

For OpenCode, configure in your ~/.opencode/config.json:

{
  "mcpServers": {
    "billionverify": {
      "command": "curl",
      "args": ["--stdio", "https://mcp.billionverify.com/mcp?api_key=YOUR_API_KEY"]
    }
  }
}

Gemini CLI Setup

For Gemini CLI, add to your configuration:

{
  "mcpServers": {
    "billionverify": {
      "command": "curl",
      "args": ["--stdio", "https://mcp.billionverify.com/mcp?api_key=YOUR_API_KEY"]
    }
  }
}

Cursor Setup

In Cursor, go to Settings > MCP and add:

{
  "billionverify": {
    "command": "curl",
    "args": ["--stdio", "https://mcp.billionverify.com/mcp?api_key=YOUR_API_KEY"]
  }
}

NPX Method (Alternative)

If you prefer the npm package approach:

{
  "mcpServers": {
    "billionverify": {
      "command": "npx",
      "args": ["-y", "@billionverify/mcp-server"],
      "env": {
        "BV_API_KEY": "your-api-key-here"
      }
    }
  }
}

Available Tools

verify_single_email

Verify a single email address with comprehensive validation.

Parameters:

Returns:

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

Example usage in Claude:

"Check if test@example.com is a valid email"

verify_batch_emails

Verify multiple email addresses at once (max 50).

Parameters:

Returns:

{
  "total_emails": 2,
  "valid_emails": 2,
  "invalid_emails": 0,
  "results": [...],
  "credits_used": 2,
  "process_time": 4
}

Example usage in Claude:

"Verify these emails: user1@example.com, user2@test.com, info@company.com"

get_account_balance

Check account credits and usage statistics.

Parameters: None

Returns:

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

Example usage in Claude:

"How many verification credits do I have left?"

health_check

Check MCP server health status.

Parameters: None

Returns:

{
  "status": "healthy",
  "version": "2.1.0",
  "service": "billionverify-mcp",
  "mode": "api-proxy"
}

get_task_status

Query file verification task progress.

Parameters:

Returns:

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

Example usage in Claude:

"What's the status of my file verification task job-123?"

get_download_url

Get verification results download link with optional status filters.

Parameters:

Example usage in Claude:

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

create_webhook

Create a webhook to receive verification completion notifications.

Parameters:

Returns:

{
  "id": "webhook-uuid",
  "url": "https://your-server.com/webhook",
  "events": ["file.completed"],
  "secret": "hmac-secret-for-signature",
  "is_active": true
}

Note: The secret is only returned once at creation. Save it for signature verification.

Example usage in Claude:

"Create a webhook to notify me when file verification completes"

list_webhooks

List all webhooks for the current account.

Parameters: None

Returns:

{
  "total": 1,
  "webhooks": [
    {
      "id": "webhook-uuid",
      "url": "https://your-server.com/webhook",
      "events": ["file.completed"],
      "is_active": true
    }
  ]
}

Example usage in Claude:

"Show me all my configured webhooks"

delete_webhook

Delete a specific webhook.

Parameters:

Example usage in Claude:

"Delete the webhook with ID webhook-123"

Usage Examples

Basic Verification

User:

Verify john@google.com

Claude:

I'll verify that email address for you.

Email Verification Result

Field	Value
Email	john@google.com
Status	Valid
Deliverable	Yes
Disposable	No
Score	0.95

This email appears to be valid and deliverable.

Multiple Email Verification

User:

Check these emails: john@google.com, test@mailinator.com, support@microsoft.com

Claude:

I'll verify all three email addresses.

Email	Status	Notes
john@google.com	Valid	Deliverable, corporate email
test@mailinator.com	Invalid	Disposable email, recommend rejecting
support@microsoft.com	Valid	Role-based address, may be shared

Recommendations:

• john@google.com - Safe to use
• test@mailinator.com - Temporary email, not recommended
• support@microsoft.com - Valid but likely a team inbox

Developer Workflow

User (in Claude Code):

Verify the test emails in my .env.example file

Claude:

I'll read the file and verify any email addresses found.

Found 3 email addresses in .env.example:

• TEST_EMAIL=user@example.com
• ADMIN_EMAIL=admin@company.com
• SUPPORT_EMAIL=help@temp-mail.org

Verification results:

Email	Status
user@example.com	Unknown (example domain)
admin@company.com	Valid
help@temp-mail.org	Invalid (disposable)

Consider using real email addresses for testing.

Output Format

The MCP server returns well-formatted results:

## Email Verification Result

**Email:** test@example.com
**Status:** VALID
**Confidence Score:** 95.0%

### Details
| Check | Result |
|-------|--------|
| Deliverable | Yes |
| Valid Format | Yes |
| Valid Domain | Yes |
| Valid MX | Yes |
| Disposable | No |
| Role Address | No |
| Catch-all | No |
| Free Provider | No |

**Credits Used:** 1

Best Practices

1. Store API Key Securely

Never hardcode your API key. Use environment variables:

{
  "env": {
    "BV_API_KEY": "${BV_API_KEY}"
  }
}

2. Use Natural Language

The MCP server understands various phrasings:

• "Verify user@example.com"
• "Is test@company.com a valid email?"
• "Check if this email is deliverable: john@test.com"
• "Can you validate these email addresses for me?"

3. Batch When Possible

For multiple emails, ask Claude to verify them together for efficiency:

"Verify all these emails at once: email1@test.com, email2@test.com, email3@test.com"

Troubleshooting

MCP Server Not Found

If Claude says it can't find the BillionVerify tool:

1. Check your configuration file path
2. Ensure the JSON is valid
3. Restart Claude Desktop completely
4. Verify your API key is correct

Rate Limit Errors

If you see rate limit errors:

1. Check your remaining credits with "How many credits do I have?"
2. Wait a moment and try again
3. Consider upgrading your plan for higher limits

Connection Issues

If verification fails:

1. Check your internet connection
2. Verify your API key is valid
3. Try a simple verification first

FAQ

Is my API key secure?

Yes. The API key is stored in your local configuration file and only used by the MCP server running on your machine. It's never sent to third parties.

Which AI clients support MCP?

Any MCP-compatible client works, including Claude Desktop, Claude Code, Cursor, Zed, Cline, and Continue.

What happens when offline?

If the BillionVerify API is unreachable, the tool returns an error message. This doesn't affect Claude's other capabilities.

How do credits work?

Each email verification uses 1 credit. Bulk verifications use 1 credit per email. Check your balance with the check_credits tool.

Next Steps