MCP Server

Model Context Protocol (MCP) é um padrão aberto que permite que clientes de IA chamem ferramentas externas por meio de uma interface compartilhada. A BillionVerify oferece um servidor MCP hospedado para verificação de e-mails, relatórios de conta, download de resultados e gerenciamento de webhooks via Streamable HTTP.

Importante

O servidor MCP da BillionVerify não oferece suporte a parâmetros de consulta ?api_key=..., URIs de recurso com chave de API embutida ou argumentos de ferramenta api_key.

Se você usava curl --stdio "https://mcp.billionverify.com/mcp?api_key=...", esse fluxo não é mais suportado. Use um cliente MCP remoto com suporte a OAuth. Se o seu cliente só aceita stdio local + API keys, use a API REST da BillionVerify em vez de MCP.

O que você pode fazer

• Verificar um único endereço de e-mail
• Verificar até 50 e-mails em uma única chamada em lote
• Consultar o saldo de créditos da conta
• Acompanhar o status de tarefas assíncronas de verificação
• Gerar links filtrados de download para jobs concluídos
• Consultar histórico e estatísticas agregadas de verificação
• Criar, listar e remover webhooks de notificações

Como a autenticação funciona

O BillionVerify MCP usa um fluxo padrão de OAuth remoto:

1. Seu cliente MCP descobre os metadados do recurso protegido em https://mcp.billionverify.com/.well-known/oauth-protected-resource.
2. O cliente segue automaticamente os metadados publicados do authorization server.
3. Você faz login com sua conta BillionVerify e aprova os scopes solicitados.
4. Depois disso, o cliente chama https://mcp.billionverify.com/mcp com Authorization: Bearer <access_token>.

Scopes disponíveis

Conectar a partir do ChatGPT

Se você vai conectar a BillionVerify a partir do ChatGPT, use esta URL do servidor MCP remoto:

https://mcp.billionverify.com/mcp

O ChatGPT descobrirá automaticamente os metadados OAuth do recurso protegido, redirecionará você para login e consentimento da BillionVerify e depois chamará o servidor MCP com um access token.

Depois de aprovar a conexão, você pode pedir coisas como:

• 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

Conectar a partir de outros clientes MCP

Qualquer cliente MCP que suporte:

• MCP remoto sobre Streamable HTTP
• OAuth-protected resources
• autenticação padrão com Bearer token

pode se conectar ao mesmo endpoint:

https://mcp.billionverify.com/mcp

Use o fluxo de configuração de MCP remoto do seu cliente e informe a URL acima. Não envolva o servidor com curl --stdio e não coloque API key na URL.

Quando usar a API REST em vez disso

Use a API REST da BillionVerify em vez de MCP se:

• seu cliente só suporta servidores MCP locais via stdio
• sua integração depende de API keys em vez de OAuth
• você está construindo automação backend-to-backend sem um cliente MCP

As API keys continuam existindo para a API REST da BillionVerify. Elas apenas não fazem mais parte do modelo de autenticação do MCP.

Ferramentas disponíveis

Recursos disponíveis

Exemplos de prompts

Verificar um único e-mail

Verify john@google.com

Verificação em lote

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

Saldo da conta

How many BillionVerify credits do I have left?

Histórico de verificação

Show my 20 most recent verification jobs

Baixar resultados filtrados

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

Gerenciamento de webhooks

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

Exemplos de respostas 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"
}

Solução de problemas

Recebo 401, um prompt de OAuth ou mcp/www_authenticate

Normalmente isso significa que o cliente ainda não concluiu a autorização OAuth, que o access token expirou ou que falta algum scope obrigatório. Reconecte o servidor MCP e aprove os scopes solicitados.

Meu cliente só suporta curl --stdio ou configuração JSON local com API keys

Esse cliente não é compatível com o modelo atual de autenticação remota MCP da BillionVerify. Use a API REST da BillionVerify em vez disso.

Eu usava ?api_key=... antes e agora não funciona mais

Esse fluxo legado foi removido da superfície MCP. Troque para um cliente MCP com suporte a OAuth e conecte-se diretamente ao endpoint remoto.

Como funcionam os créditos?

• E-mail válido: 1 crédito
• E-mail inválido: 0 créditos
• E-mail desconhecido: 0 créditos

Use get_account_balance para verificar o saldo restante.

FAQ

O servidor MCP suporta API keys?

Não. O servidor MCP remoto exige access tokens OAuth. As API keys de desenvolvedor são para a API REST, não para iniciar a conexão MCP.

Quais clientes são suportados?

Qualquer cliente que suporte MCP remoto sobre Streamable HTTP e OAuth-protected resources pode se conectar. O ChatGPT é um exemplo. Para clientes sem suporte a MCP OAuth remoto, use a API REST.

Preciso instalar um pacote npm?

Não. Este é um servidor MCP remoto hospedado. Você se conecta diretamente a https://mcp.billionverify.com/mcp.

Posso buscar histórico e estatísticas via MCP?

Sim. Use get_verification_history, get_verification_stats ou os recursos equivalentes somente leitura.

Próximos passos