Aller au contenu

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. Les agents sont disponibles à partir du plan Starter ; le plan Free ne peut pas en créer. 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 Desktop

Réglages, puis Connecteurs, puis Ajouter un connecteur personnalisé, avec l'URL https://mcp.pricklymails.com/mcp. 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. Prend un argument api_key, une clé pm_live_ ou pm_test_ de votre compte, collée dans la conversation ou générée avec create_api_key.
  • 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. 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. Les chunks suivants passent toujours par le jeu de checks complet du plan. 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. L'identité de l'agent (sa session OAuth) est distincte de l'identifiant de vérification (une clé API) : l'agent s'authentifie via OAuth, puis vérifie avec les clés API de votre compte, la même séparation que l'API REST utilise elle-même entre une session dashboard et une clé pm_.