Serveur MCP

PricklyMails expose un serveur Model Context Protocol (MCP) distant, pour qu'un agent IA (Claude, par exemple) vérifie des adresses email comme un outil au lieu que vous câbliez l'API REST à la main. Il est hébergé à https://mcp.pricklymails.com/mcp.

Créez d'abord un agent

Connecter un client nécessite un agent scopé, créé depuis la page Agents du dashboard. Le plan Free crée un agent, limité à la vérification d'une adresse à la fois et à la lecture des résultats ; chaque plan payant peut accorder à un agent n'importe quelle portée. Les scopes que vous accordez à l'agent régissent ce qu'un client connecté peut faire à travers lui, et vous pouvez révoquer l'agent à tout moment pour couper l'accès immédiatement.

Connecter Claude

Dans Claude ou Claude Desktop, ouvrez Customize puis Connectors, cliquez sur + Add, puis sur Add custom connector, avec l'URL https://mcp.pricklymails.com/mcp. Sur une offre Team ou Enterprise, un propriétaire l'ajoute une fois pour toute l'organisation, depuis Organization settings puis Connectors. L'authentification est OAuth 2.1 : vous vous connectez, puis approuvez un de vos agents sur l'écran de consentement. Aucune clé API n'est jamais collée dans la configuration du connecteur.

Outils disponibles

Vérification :

• verify_email : vérifie une adresse. Accepte un argument api_key optionnel, une clé pm_live_ ou pm_test_, pour facturer et limiter l'appel au compte de cette clé ; sans lui, la vérification est facturée au compte que vous avez connecté.
• get_verification : récupère le résultat d'un job précédent par UUID.

Vérification en masse :

• submit_batch : soumet jusqu'à 4096 emails pour une vérification en masse, facturés par adresse unique valide. Un lot compte au moins 20 adresses valides distinctes ; vérifiez-en moins avec verify_email. Vous pouvez passer checks, les contrôles à lancer ; sans lui, le lot lance tous les contrôles de votre offre. Vous pouvez passer custom_ids, une référence client par email (alignée par index avec emails), réémise telle quelle dans get_batch_results pour rattacher un résultat à votre propre ligne d'entrée sans dépendre de l'ordre. Utilisez votre propre identifiant de ligne, jamais l'adresse email ou une autre donnée personnelle : l'email brut n'est jamais stocké.
• append_batch_emails : ajoute un chunk à un batch ouvert (créé avec final: false) pour dépasser la limite d'une seule requête. Accepte les mêmes checks optionnels que submit_batch : passez les mêmes à chaque chunk pour que tout le lot lance un seul jeu de contrôles. Le chunk qui ferme le lot est refusé tant que le lot compterait moins de 20 adresses valides distinctes, et le lot reste ouvert. Accepte les mêmes custom_ids optionnels que submit_batch, alignés sur les emails de ce chunk.
• get_batch : récupère le statut, la progression et les résultats agrégés d'un lot par UUID.
• get_batch_results : récupère les résultats par email d'un lot. Chaque ligne porte custom_id, la référence client fournie au submit pour cet email (le cas échéant).
• list_batches : liste les lots de l'appelant, du plus récent au plus ancien.

Clés API :

• create_api_key : génère une clé API sur votre compte. Nécessite le scope api_keys:create.
• list_api_keys : liste les clés de l'appelant avec leurs scopes et contrôles activés. Nécessite api_keys:read.
• revoke_api_key : révoque une clé par UUID, idempotent en cas de répétition. Nécessite api_keys:revoke.

Webhooks :

• create_webhook : enregistre un webhook de notification de fin de job, renvoyant son secret de signature une seule fois. Nécessite webhooks:create.
• list_webhooks : liste les endpoints webhook de l'appelant. Nécessite webhooks:read.
• get_webhook : récupère un endpoint par UUID. Nécessite webhooks:read.
• update_webhook : met à jour l'url, les événements, la description ou le statut d'un endpoint. Nécessite webhooks:update.
• delete_webhook : supprime un endpoint par UUID, idempotent en cas de répétition. Nécessite webhooks:delete.

Compte :

• check_balance : lit le solde du portefeuille de jetons, la dépense quotidienne moyenne et le plan actif. Nécessite billing:read.
• list_transactions : lit le grand livre du portefeuille, du plus récent au plus ancien. Nécessite billing:read.
• list_jobs : liste les jobs de vérification autonomes de l'appelant, du plus récent au plus ancien. Nécessite results:read.
• get_usage : lit l'aperçu d'usage des vérifications sur la fenêtre par défaut. Nécessite usage:read.
• get_pricing : lit la grille tarifaire publique, le tarif de recharge et le coût par contrôle. Aucun scope requis.

Scopes

Le serveur annonce douze scopes : email:verify:single, email:verify:bulk, results:read, billing:read, usage:read, api_keys:create, api_keys:read, api_keys:revoke, webhooks:read, webhooks:create, webhooks:update, et webhooks:delete. N'accordez à un agent que les scopes correspondant aux outils que vous voulez qu'il utilise.

Facturation et identifiants

Une vérification lancée via verify_email facture votre portefeuille de jetons exactement comme l'API REST ; une clé pm_test_ exécute le bac à sable déterministe et n'est jamais facturée. La session OAuth de l'agent suffit pour vérifier : verify_email, get_verification, submit_batch et append_batch_emails facturent le portefeuille du compte connecté, dans la limite des scopes accordés à l'agent. Passez api_key sur l'un de ces appels pour facturer à la place un autre compte dont vous détenez une clé pm_, ou une clé pm_test_ pour rester dans le bac à sable.