MCP Server

Model Context Protocol (MCP) est un standard ouvert qui permet aux clients IA d'appeler des outils externes via une interface commune. BillionVerify propose un serveur MCP hébergé pour la vérification d'e-mails, les rapports de compte, le téléchargement de résultats et la gestion des webhooks via Streamable HTTP.

Important

Le serveur MCP de BillionVerify ne prend pas en charge les paramètres de requête ?api_key=..., les URI de ressources avec clé API intégrée ni les arguments d'outil api_key.

Si vous utilisiez auparavant curl --stdio "https://mcp.billionverify.com/mcp?api_key=...", ce flux n'est plus pris en charge. Utilisez à la place un client MCP distant compatible OAuth. Si votre client ne prend en charge que stdio local + clés API, utilisez l'API REST BillionVerify plutôt que MCP.

Ce que vous pouvez faire

• Vérifier une adresse e-mail unique
• Vérifier jusqu'à 50 e-mails dans un seul lot
• Consulter le solde de crédits du compte
• Suivre l'état des tâches asynchrones de vérification
• Générer des liens de téléchargement filtrés pour les jobs terminés
• Lire l'historique et les statistiques agrégées de vérification
• Créer, lister et supprimer des webhooks de notifications

Comment fonctionne l'authentification

BillionVerify MCP utilise un flux OAuth distant standard :

1. Votre client MCP découvre les métadonnées de ressource protégée via https://mcp.billionverify.com/.well-known/oauth-protected-resource.
2. Le client suit automatiquement les métadonnées du serveur d'autorisation annoncées.
3. Vous vous connectez avec votre compte BillionVerify et approuvez les scopes demandés.
4. Le client appelle ensuite https://mcp.billionverify.com/mcp avec Authorization: Bearer <access_token>.

Scopes disponibles

Connexion depuis ChatGPT

Si vous connectez BillionVerify depuis ChatGPT, utilisez cette URL du serveur MCP distant :

https://mcp.billionverify.com/mcp

ChatGPT découvrira automatiquement les métadonnées OAuth de la ressource protégée, vous redirigera vers la connexion et le consentement BillionVerify, puis appellera le serveur MCP avec un access token.

Une fois la connexion autorisée, vous pouvez demander par exemple :

• 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

Connexion depuis d'autres clients MCP

Tout client MCP qui prend en charge :

• MCP distant via Streamable HTTP
• OAuth-protected resources
• l'authentification standard par Bearer token

peut se connecter au même endpoint :

https://mcp.billionverify.com/mcp

Utilisez le flux de configuration MCP distante de votre client et fournissez l'URL ci-dessus. N'enveloppez pas le serveur dans curl --stdio et n'ajoutez pas de clé API dans l'URL.

Quand utiliser l'API REST à la place

Utilisez l'API REST BillionVerify au lieu de MCP si :

• votre client ne prend en charge que des serveurs MCP locaux via stdio
• votre intégration dépend de clés API au lieu d'OAuth
• vous construisez une automatisation backend-to-backend sans client MCP

Les clés API existent toujours pour l'API REST BillionVerify. Elles ne font simplement plus partie du modèle d'authentification MCP.

Outils disponibles

Ressources disponibles

Exemples de prompts

Vérifier un seul e-mail

Verify john@google.com

Vérification par lot

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

Solde du compte

How many BillionVerify credits do I have left?

Historique de vérification

Show my 20 most recent verification jobs

Télécharger des résultats filtrés

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

Gestion des webhooks

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

Exemples de réponses 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"
}

Dépannage

Je reçois 401, une invite OAuth ou mcp/www_authenticate

Cela signifie généralement que le client n'a pas terminé l'autorisation OAuth, que l'access token a expiré ou qu'il manque un scope requis. Reconnectez le serveur MCP et approuvez les scopes demandés.

Mon client ne prend en charge que curl --stdio ou une configuration JSON locale avec clé API

Ce client n'est pas compatible avec le modèle actuel d'authentification MCP distante de BillionVerify. Utilisez plutôt l'API REST BillionVerify.

J'utilisais ?api_key=... auparavant et cela ne fonctionne plus

Ce flux legacy a été retiré de la surface MCP. Passez à un client MCP compatible OAuth et connectez directement l'endpoint distant.

Comment fonctionnent les crédits ?

• E-mail valide : 1 crédit
• E-mail invalide : 0 crédit
• E-mail inconnu : 0 crédit

Utilisez get_account_balance pour consulter votre solde restant.

FAQ

Le serveur MCP prend-il en charge les clés API ?

Non. Le serveur MCP distant exige des access tokens OAuth. Les clés API développeur sont destinées à l'API REST, pas à l'initialisation de la connexion MCP.

Quels clients sont pris en charge ?

Tout client compatible avec MCP distant via Streamable HTTP et OAuth-protected resources peut se connecter. ChatGPT en est un exemple. Pour les clients sans prise en charge MCP OAuth distante, utilisez l'API REST.

Dois-je installer un package npm ?

Non. Il s'agit d'un serveur MCP distant hébergé. Vous vous connectez directement à https://mcp.billionverify.com/mcp.

Puis-je récupérer l'historique et les statistiques via MCP ?

Oui. Utilisez get_verification_history, get_verification_stats ou les ressources équivalentes en lecture seule.

Étapes suivantes