MCP Server

Model Context Protocol (MCP) é um protocolo aberto da Anthropic que permite que modelos de IA interajam de forma segura com ferramentas externas e fontes de dados. BillionVerify fornece capacidades de verificação de e-mail de nível empresarial para agentes de IA através do HTTP Streamable Transport, tornando a integração incrivelmente simples.

Por que Agentes de IA Precisam de Verificação de E-mail

Casos de uso modernos de agentes de IA incluem:

• Claude Code precisa verificar endereços de e-mail ao processar dados de usuários
• OpenCode requer validação de e-mail em fluxos de trabalho automatizados
• Gemini CLI agentes precisam de garantia de qualidade ao lidar com dados de registro
• Codex código gerado precisa de lógica de verificação de e-mail integrada
• Agentes de IA Personalizados precisam confirmar a autenticidade de contatos ao interagir com humanos

BillionVerify MCP permite que qualquer agente de IA chame diretamente serviços de verificação de e-mail de nível empresarial através do padrão HTTP Streamable Transport - sem configuração complexa necessária.

Recursos Principais

1. Verificação de E-mail Único em Tempo Real

• Verificar formato de e-mail, domínio e registros MX
• Verificação de conexão SMTP opcional
• Detecção de e-mail descartável
• Identificação de e-mail corporativo vs gratuito
• Detecção de e-mail baseado em função (support@, noreply@, etc.)
• Tempo médio de resposta < 2 segundos

2. Verificação de E-mail em Lote

• Verificar até 50 e-mails de uma vez
• Processamento concorrente para eficiência
• Resultados detalhados e estatísticas

3. Sistema de Cache Inteligente

• E-mails válidos em cache por 7 dias
• E-mails inválidos em cache por 7 dias
• Status desconhecido em cache por 10 minutos
• Reduz verificações repetidas desnecessárias

4. Cobrança Precisa de Créditos

• E-mail válido: 1 crédito
• E-mail inválido: 0 créditos (previne desperdício)
• Status desconhecido: 0 créditos (tentativa automática)
• Consultas de saldo em tempo real

Clientes de IA Suportados

Configuração Rápida (HTTP Transport - Recomendado)

A maneira mais simples de integrar - sem pacotes npm para instalar!

Passo 1: Obter Chave API

Visite o Painel BillionVerify para criar sua chave API.

Passo 2: Configurar Claude Desktop

Edite o arquivo de configuração:

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

Substitua YOUR_API_KEY pela sua chave API real, depois reinicie o Claude Desktop.

É só isso! Sem npm install, sem dependências. curl está pré-instalado em todos os sistemas. Claude agora tem capacidades de verificação de e-mail.

Passo 3: Começar a Verificar

Na sua conversa, simplesmente pergunte:

Por favor, verifique este e-mail: user@example.com

Claude chamará automaticamente o BillionVerify e retornará resultados detalhados.

Configuração do Claude Code

Para Claude Code CLI, adicione o servidor MCP:

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

Ou adicione ao seu ~/.claude.json:

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

Configuração do OpenCode

Para OpenCode, configure no seu ~/.opencode/config.json:

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

Configuração do Gemini CLI

Para Gemini CLI, adicione à sua configuração:

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

Configuração do Cursor

No Cursor, vá para Settings > MCP e adicione:

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

Método NPX (Alternativo)

Se você preferir a abordagem do pacote npm:

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

Ferramentas Disponíveis

verify_single_email

Verifica um único endereço de e-mail com validação abrangente.

Parâmetros:

Retorna:

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

Exemplo de uso no Claude:

"Verifique se test@example.com é um e-mail válido"

verify_batch_emails

Verifica múltiplos endereços de e-mail de uma vez (máx 50).

Parâmetros:

Retorna:

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

Exemplo de uso no Claude:

"Verifique estes e-mails: user1@example.com, user2@test.com, info@company.com"

get_account_balance

Verifica créditos da conta e estatísticas de uso.

Parâmetros: Nenhum

Retorna:

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

Exemplo de uso no Claude:

"Quantos créditos de verificação me restam?"

health_check

Verifica o status de saúde do servidor MCP.

Parâmetros: Nenhum

Retorna:

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

get_task_status

Consulta o progresso da tarefa de verificação de arquivo.

Parâmetros:

Retorna:

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

Exemplo de uso no Claude:

"Qual é o status da minha tarefa de verificação de arquivo job-123?"

get_download_url

Obtém link de download dos resultados de verificação com filtros de status opcionais.

Parâmetros:

Exemplo de uso no Claude:

"Obter link de download apenas para e-mails válidos do job-123"

create_webhook

Cria um webhook para receber notificações de conclusão de verificação.

Parâmetros:

Retorna:

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

Nota: O secret é retornado apenas uma vez na criação. Salve-o para verificação de assinatura.

Exemplo de uso no Claude:

"Criar um webhook para me notificar quando a verificação de arquivo terminar"

list_webhooks

Lista todos os webhooks da conta atual.

Parâmetros: Nenhum

Retorna:

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

Exemplo de uso no Claude:

"Mostre-me todos os meus webhooks configurados"

delete_webhook

Exclui um webhook específico.

Parâmetros:

Exemplo de uso no Claude:

"Excluir o webhook com ID webhook-123"

Exemplos de Uso

Verificação Básica

Usuário:

Verifique john@google.com

Claude:

Vou verificar esse endereço de e-mail para você.

Resultado da Verificação de E-mail

Campo	Valor
E-mail	john@google.com
Status	Válido
Entregável	Sim
Descartável	Não
Pontuação	0.95

Este e-mail parece ser válido e entregável.

Verificação de Múltiplos E-mails

Usuário:

Verifique estes e-mails: john@google.com, test@mailinator.com, support@microsoft.com

Claude:

Vou verificar todos os três endereços de e-mail.

E-mail	Status	Notas
john@google.com	Válido	Entregável, e-mail corporativo
test@mailinator.com	Inválido	E-mail descartável, recomendo rejeitar
support@microsoft.com	Válido	Endereço de função, pode ser compartilhado

Recomendações:

• john@google.com - Seguro para usar
• test@mailinator.com - E-mail temporário, não recomendado
• support@microsoft.com - Válido mas provavelmente uma caixa de entrada de equipe

Fluxo de Trabalho do Desenvolvedor

Usuário (no Claude Code):

Verifique os e-mails de teste no meu arquivo .env.example

Claude:

Vou ler o arquivo e verificar os endereços de e-mail encontrados.

Encontrados 3 endereços de e-mail em .env.example:

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

Resultados da verificação:

E-mail	Status
user@example.com	Desconhecido (domínio de exemplo)
admin@company.com	Válido
help@temp-mail.org	Inválido (descartável)

Considere usar endereços de e-mail reais para testes.

Formato de Saída

O servidor MCP retorna resultados bem formatados:

## Resultado da Verificação de E-mail

**E-mail:** test@example.com
**Status:** VÁLIDO
**Pontuação de Confiança:** 95.0%

### Detalhes
| Verificação | Resultado |
|-------------|-----------|
| Entregável | Sim |
| Formato Válido | Sim |
| Domínio Válido | Sim |
| MX Válido | Sim |
| Descartável | Não |
| Endereço de Função | Não |
| Catch-all | Não |
| Provedor Gratuito | Não |

**Créditos Usados:** 1

Melhores Práticas

1. Armazene a Chave API com Segurança

Nunca codifique sua chave API diretamente. Use variáveis de ambiente:

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

2. Use Linguagem Natural

O servidor MCP entende várias formulações:

• "Verifique user@example.com"
• "test@company.com é um e-mail válido?"
• "Verifique se este e-mail é entregável: john@test.com"
• "Você pode validar estes endereços de e-mail para mim?"

3. Processe em Lote Quando Possível

Para múltiplos e-mails, peça ao Claude para verificá-los juntos para maior eficiência:

"Verifique todos estes e-mails de uma vez: email1@test.com, email2@test.com, email3@test.com"

Solução de Problemas

Servidor MCP Não Encontrado

Se o Claude disser que não consegue encontrar a ferramenta BillionVerify:

1. Verifique o caminho do arquivo de configuração
2. Certifique-se de que o JSON é válido
3. Reinicie o Claude Desktop completamente
4. Verifique se sua chave API está correta

Erros de Limite de Taxa

Se você vir erros de limite de taxa:

1. Verifique seus créditos restantes com "Quantos créditos eu tenho?"
2. Aguarde um momento e tente novamente
3. Considere atualizar seu plano para limites mais altos

Problemas de Conexão

Se a verificação falhar:

1. Verifique sua conexão com a internet
2. Verifique se sua chave API é válida
3. Tente uma verificação simples primeiro

FAQ

Minha chave API está segura?

Sim. A chave API é armazenada em seu arquivo de configuração local e usada apenas pelo servidor MCP executando em sua máquina. Nunca é enviada para terceiros.

Quais clientes de IA suportam MCP?

Qualquer cliente compatível com MCP funciona, incluindo Claude Desktop, Claude Code, Cursor, Zed, Cline e Continue.

O que acontece quando estou offline?

Se a API BillionVerify estiver inacessível, a ferramenta retorna uma mensagem de erro. Isso não afeta as outras capacidades do Claude.

Como funcionam os créditos?

Cada verificação de e-mail usa 1 crédito. Verificações em lote usam 1 crédito por e-mail. Verifique seu saldo com a ferramenta check_credits.

Próximos Passos