Assistants IA (serveur MCP)

Le serveur MCP de YesWeCheck donne à votre assistant IA les outils de vérification d'adresses et de recherche d'email BtoB. Vous lui parlez normalement, il appelle YesWeCheck quand c'est utile. Il applique les réglages de votre compte (contrôles, SMTP, politique de validation, listes) et débite les mêmes crédits.

https://api.yeswecheck.fr/mcp

Le protocole est le Model Context Protocol, en transport HTTP Streamable. Tout client MCP compatible peut s'y connecter.

ChatGPTClaudeLe Chat (Mistral)Claude CodeCursorVS Code

Ce que vous pouvez demander

• « Vérifie l'adresse [email protected]. »
• « Voici 300 adresses d'un salon : lesquelles sont invalides ? »
• « Combien de crédits coûterait cette liste ? » (estimation, rien n'est débité)
• « Trouve l'email professionnel de Marie Martin chez acme.fr. »
• « Où en est le nettoyage lancé ce matin ? »
• « Combien me reste-t-il de crédits ? »

Installer

Deux façons de se connecter :

• OAuth (Claude, ChatGPT, Le Chat, Claude Code, Cursor, VS Code) : vous collez l'adresse du serveur, une page YesWeCheck s'ouvre, vous choisissez les droits et cliquez Autoriser. Aucune clé à copier.
• Clé API (scripts, agents, CI, serveurs sans navigateur) : une clé MCP dédiée envoyée dans l'en-tête Authorization. Voir Se connecter avec une clé API.

L'adresse du serveur et ces mêmes étapes sont aussi dans l'espace client : Intégrer → Connecteurs → Assistants IA.

Claude

Claude

1. Dans Claude (web ou Desktop), ouvrez le menu Connecteurs et ajoutez un connecteur personnalisé.
2. Nommez-le YesWeCheck et collez l'adresse du serveur.
3. Cliquez Se connecter : la page YesWeCheck s'ouvre ; choisissez les droits, puis Autoriser.
4. Activez le connecteur dans la conversation et posez votre question.

Sur une offre Team ou Enterprise, le connecteur est d'abord ajouté par un propriétaire de l'espace Claude.

ChatGPT

ChatGPT

1. Dans ChatGPT, ajoutez un serveur MCP personnalisé (rubrique des applications ou connecteurs, en mode développeur selon votre offre).
2. Collez l'adresse du serveur et choisissez l'authentification OAuth.
3. Connectez-vous à YesWeCheck quand la page s'ouvre, choisissez les droits, puis Autoriser.

Les serveurs MCP personnalisés dépendent de l'offre ChatGPT et de la configuration de votre espace.

Le Chat (Mistral)

Le Chat (Mistral)

1. Dans Le Chat, ouvrez Connecteurs, cliquez Ajouter un connecteur, puis l'onglet Connecteur MCP personnalisé.
2. Nommez-le YesWeCheck et collez l'adresse du serveur : Le Chat détecte la connexion OAuth.
3. Connectez-vous à YesWeCheck quand la page s'ouvre, choisissez les droits, puis Autoriser.

Dans un espace d'équipe Le Chat, l'ajout d'un connecteur personnalisé est réservé aux administrateurs.

Claude Code

Claude Code

claude mcp add --transport http yeswecheck https://api.yeswecheck.fr/mcp

Dans Claude Code, tapez /mcp puis choisissez yeswecheck : le navigateur ouvre la page d'autorisation YesWeCheck.

Sans navigateur (serveur, CI), utilisez une clé API.

Cursor

Cursor

Ajoutez le serveur dans le fichier mcp.json de Cursor (réglages MCP) :

{
  "mcpServers": {
    "yeswecheck": { "url": "https://api.yeswecheck.fr/mcp" }
  }
}

Cursor détecte la connexion OAuth : cliquez Se connecter, puis Autoriser sur la page YesWeCheck.

VS Code

VS Code

Ajoutez le serveur avec la commande MCP: Add Server, ou dans .vscode/mcp.json :

{
  "servers": {
    "yeswecheck": { "type": "http", "url": "https://api.yeswecheck.fr/mcp" }
  }
}

Démarrez le serveur : VS Code ouvre la page d'autorisation YesWeCheck.

Autoriser l'accès

La page d'autorisation s'ouvre sur app.yeswecheck.fr ; connectez-vous si besoin, avec vos moyens habituels (mot de passe, Google, GitHub, double authentification). Elle affiche l'application qui demande l'accès et l'adresse vers laquelle vous serez renvoyé.

Réglage	Par défaut	Effet
Organisation	Celle de votre session (Changer de compte pour une autre)	L'assistant agit pour elle seule
Vérifier des adresses email	Toujours accordé	Outils de validation, de suivi des lots et de crédits
Trouver l'email professionnel d'une personne	Coché si l'application le demande	Outil find_btob_email
Vérification de la boîte (SMTP)	Activée	1 crédit par adresse vérifiée en SMTP (voir Crédits)
Plafond de crédits par jour	500 (vide = aucun plafond)	Au-delà, les validations avec SMTP de cette connexion sont refusées jusqu'au lendemain

Seuls les propriétaires et administrateurs de l'organisation peuvent autoriser une application ; un membre ne peut que refuser.

À l'autorisation, YesWeCheck crée une clé API dédiée à cette application, nommée MCP – <nom de l'application>. Elle porte les réglages choisis ; son secret n'est jamais affiché. Vous la retrouvez dans Clés API, avec le badge MCP · OAuth, où vous pouvez modifier ses contrôles, son plafond ou ses restrictions d'IP comme pour toute clé.

L'application reçoit un jeton d'accès valable une heure, renouvelé automatiquement pendant 30 jours d'utilisation. Une application inactive plus de 30 jours demande de se reconnecter.

Se connecter avec une clé API

Pour un script, un agent sur serveur ou une intégration continue, créez une clé MCP dans Intégrer → Connecteurs → Assistants IA, onglet Scripts et agents : choisissez le SMTP, la recherche BtoB et un plafond journalier. Le secret ywc_live_… n'est affiché qu'une fois.

Une clé par agent : elle se révoque seule, sans couper vos autres intégrations. Une clé API ordinaire fonctionne aussi, avec ses propres réglages ; la recherche BtoB s'y active dans la clé, option Finder BtoB pour les agents IA (bloc Agents IA (MCP), désactivée par défaut).

Claude Code

Claude Code

claude mcp add --transport http yeswecheck https://api.yeswecheck.fr/mcp \
  --header "Authorization: Bearer ywc_live_…"

Ou, dans le fichier .mcp.json du projet, avec la clé dans la variable d'environnement YWC_API_KEY :

{
  "mcpServers": {
    "yeswecheck": {
      "type": "http",
      "url": "https://api.yeswecheck.fr/mcp",
      "headers": { "Authorization": "Bearer ${YWC_API_KEY}" }
    }
  }
}

Cursor

Cursor

{
  "mcpServers": {
    "yeswecheck": {
      "url": "https://api.yeswecheck.fr/mcp",
      "headers": { "Authorization": "Bearer ${env:YWC_API_KEY}" }
    }
  }
}

VS Code

VS Code

VS Code demande la clé au premier démarrage et la conserve dans son stockage sécurisé :

{
  "inputs": [
    { "type": "promptString", "id": "ywc-key", "description": "Clé MCP YesWeCheck", "password": true }
  ],
  "servers": {
    "yeswecheck": {
      "type": "http",
      "url": "https://api.yeswecheck.fr/mcp",
      "headers": { "Authorization": "Bearer ${input:ywc-key}" }
    }
  }
}

TypeScript

// npm install @modelcontextprotocol/client
import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';

const transport = new StreamableHTTPClientTransport(new URL('https://api.yeswecheck.fr/mcp'), {
  requestInit: { headers: { Authorization: `Bearer ${process.env.YWC_API_KEY}` } },
});
const client = new Client({ name: 'mon-agent', version: '1.0.0' });
await client.connect(transport);

const result = await client.callTool({
  name: 'validate_email',
  arguments: { email: '[email protected]' },
});
console.log(result.structuredContent);

Python

# pip install "mcp>=2"
import asyncio, os
import httpx2
from mcp import Client
from mcp.client.streamable_http import streamable_http_client


async def main() -> None:
    async with httpx2.AsyncClient(
        headers={"Authorization": f"Bearer {os.environ['YWC_API_KEY']}"},
        timeout=httpx2.Timeout(30.0, read=120.0),
    ) as http_client:
        transport = streamable_http_client("https://api.yeswecheck.fr/mcp", http_client=http_client)
        async with Client(transport) as client:
            result = await client.call_tool("validate_email", {"email": "[email protected]"})
            print(result.structured_content)


asyncio.run(main())

n8n

Dans votre agent n8n, ajoutez l'outil MCP Client Tool :

Paramètre	Valeur
Adresse	https://api.yeswecheck.fr/mcp
Transport	HTTP Streamable
Authentification	Bearer, avec la clé MCP

cURL

curl https://api.yeswecheck.fr/mcp \
  -H "Authorization: Bearer $YWC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

La réponse arrive au format text/event-stream (un seul message data:).

Le serveur accepte uniquement Authorization: Bearer. Une clé de portée widget et un jeton de session du tableau de bord sont refusés (401/403).

Les outils

Outil	Rôle	Coût	Lecture seule
validate_email	Vérifie une adresse	1 crédit si SMTP et verdict ≠ unknown	Non
validate_emails_batch	Vérifie une liste (jusqu'à 5 000 adresses)	Idem, par adresse	Non
get_batch_job	Avancement d'un lot	Gratuit	Oui
get_batch_results	Résultats d'un lot, page par page	Gratuit	Oui
list_batch_jobs	Lots lancés par vos assistants	Gratuit	Oui
cancel_batch_job	Annule un lot en cours	Remboursement des adresses non conclues	Non
find_btob_email	Trouve l'email professionnel d'une personne	1 recherche du quota du jour, aucun crédit	Non
get_credits	Solde, plafonds de la clé, quota BtoB	Gratuit	Oui

Chaque outil renvoie un résumé lisible et une sortie structurée (structuredContent) décrite par un schéma : l'assistant lit directement les champs.

validate_email

Entrée	Description
email	L'adresse à vérifier (320 caractères au plus)

La sortie est celle de POST /v2/email/validate : result (valid, risky, invalid, unknown), score, finalDecision de votre politique, features avec le détail de chaque contrôle actif sur la clé ; plus un objet credits (used, remaining, unlimited). Si une faute de frappe est détectée, l'assistant propose l'adresse corrigée (features.typoCorrection).

Pour protéger l'assistant contre les instructions cachées dans des données de tiers, le texte libre venu de l'extérieur n'est pas transmis : réponse brute du serveur de messagerie (remplacée par un message fixe), enregistrements SPF, DMARC et BIMI, titulaire du domaine. Verdicts, scores et codes sont identiques à l'API.

validate_emails_batch

Entrée	Description
emails	1 à 5 000 adresses
label	Nom du lot dans le tableau de bord (facultatif)
dry_run	true : compte les adresses et estime les crédits, sans rien vérifier ni débiter

Les entrées sans @ sont écartées et les doublons retirés (comparaison en minuscules), comme à l'import d'un fichier. Ensuite :

• jusqu'à 25 adresses uniques : réponse immédiate, un verdict par adresse (results), avec summary par verdict et credits_used ;
• au-delà : un traitement par lots démarre en arrière-plan. La réponse donne job.job_id et le lien du lot dans le tableau de bord, où il porte le badge MCP. Un seul lot à la fois par organisation.

Avant de lancer un lot, le serveur vérifie que le solde et le plafond de la clé couvrent l'estimation (max_credits) ; sinon il refuse sans rien démarrer. En mode dry_run, blocked_by indique ce qui bloquerait.

get_batch_job

Entrée : job_id. Sortie : status (pending, processing, paused, completed, failed, cancelled), phase, percentage, processed/total, compteurs par verdict, smtp.downgraded (solde épuisé en cours de route : la suite a tourné sans SMTP) et results_ready. Un appel par minute suffit.

get_batch_results

Entrée	Description
job_id	Identifiant du lot
status	Filtre sur un verdict (facultatif)
cursor	next_cursor de la page précédente ; absent pour la première
limit	Taille de page, 100 par défaut, 500 au plus

Chaque ligne donne email, status, score et reason (les motifs des connecteurs). next_cursor vaut null sur la dernière page. Les exports CSV, Excel et le rapport PDF restent dans le tableau de bord.

list_batch_jobs et cancel_batch_job

list_batch_jobs (limit de 1 à 20, 10 par défaut) liste les lots lancés par vos assistants, du plus récent au plus ancien ; les lots importés dans le tableau de bord n'y figurent pas, et les outils de suivi ne les voient pas.

cancel_batch_job (job_id) arrête un lot en cours : les adresses sans verdict facturable sont remboursées, les verdicts déjà obtenus restent facturés, et les résultats du lot sont supprimés.

find_btob_email

Entrée	Description
first_name · last_name	Prénom et nom
domain	Domaine de l'entreprise, par exemple acme.fr (pas une URL, pas une messagerie grand public)

Les formats d'adresse probables sont testés auprès du serveur de messagerie de l'entreprise jusqu'à confirmation, en 40 secondes au plus. outcome vaut :

outcome	Signification
found	Boîte confirmée : email et son format (pattern, par exemple first.last)
accept_all	Le domaine accepte toutes les adresses : aucune boîte ne peut être confirmée
not_found	Aucun format testé n'a été accepté
incomplete	Délai atteint avant la fin des tests ; une nouvelle recherche repart de zéro

Une recherche consomme une unité du quota BtoB de l'organisation (20 par jour, partagé avec le tableau de bord), jamais un crédit. Un domaine grand public ou sans serveur de messagerie est refusé avant le quota. Les recherches d'une organisation s'exécutent une à la fois ; les adresses trouvées apparaissent aussi dans l'historique de la recherche BtoB du tableau de bord.

L'outil n'est disponible que si la recherche BtoB est accordée à la connexion (case cochée à l'autorisation, ou option Finder BtoB pour les agents IA de la clé).

get_credits

Sans entrée. Renvoie le solde de l'organisation (balance, ou unlimited), la consommation du jour et du mois de la clé avec ses plafonds, l'état du SMTP sur la clé et le quota BtoB du jour (finder).

Crédits et quotas

Les règles sont celles de l'API : voir Crédits.

Action	Coût
Validation avec SMTP, verdict valid, risky ou invalid	1 crédit
Validation avec SMTP, verdict unknown	0
Validation sans SMTP	0
dry_run, suivi des lots, résultats, get_credits	0
find_btob_email	1 recherche du quota BtoB (20 par jour et par organisation)

Le SMTP est décidé par la connexion (réglage à l'autorisation, ou configuration de la clé), jamais par l'assistant. Le plafond journalier de la connexion borne ce qu'un assistant peut dépenser, même si votre solde est plus élevé.

Limites

Élément	Limite
Adresses par appel de validate_emails_batch	5 000 (25 en réponse immédiate)
Lots en cours	1 par organisation, tous canaux confondus
Appels par clé	Mêmes limites par clé que l'API : chaque requête MCP compte, et chaque adresse d'une réponse immédiate compte comme un appel de validation
Réponse immédiate	Plus aucune adresse ne démarre après 30 secondes ; les restantes sortent unknown, sans débit
Recherche BtoB	40 secondes, une à la fois par organisation, 20 par jour
Corps d'une requête	2 Mo

Erreurs

L'authentification répond en HTTP :

Réponse	Cause
401 avec WWW-Authenticate	Jeton ou clé absent, expiré ou révoqué. Le client OAuth relance l'autorisation
403 insufficient_scope	L'outil demande un droit non accordé (recherche BtoB) ; le client propose de se reconnecter avec ce droit
403	Clé de portée widget, IP hors des restrictions de la clé
429	Trop de requêtes depuis la même IP

Les erreurs d'un outil arrivent dans son résultat (isError: true), sous la forme CODE: message, suivie de Retry after N seconds. quand attendre suffit :

Code	Cause
INSUFFICIENT_CREDITS	Solde épuisé pour une validation avec SMTP
API_KEY_BUDGET_EXCEEDED	Plafond journalier ou mensuel de la connexion atteint
RATE_LIMITED	Limite d'appels de la clé, ou recherche BtoB déjà en cours
QUOTA_EXCEEDED	Quota BtoB du jour épuisé (remis à zéro à minuit UTC)
SCOPE_REQUIRED	Recherche BtoB non accordée à cette connexion
BATCH_ALREADY_RUNNING	Un lot tourne déjà dans l'organisation
BATCH_NOT_READY	Résultats demandés avant la fin du lot
RESULTS_EXPIRED	Résultats supprimés (durée de conservation ou annulation)
NOT_FOUND	Lot inconnu, ou non lancé par un assistant de cette organisation
INVALID_STATE	Lot qui ne peut plus être annulé
INVALID_INPUT	Entrée refusée (adresse, domaine, liste vide)
FORBIDDEN	Refus des règles de protection de la clé
INTERNAL_ERROR	Erreur interne ; réessayez plus tard

Rien n'est débité sur une erreur.

Sécurité

• Une identité par application : chaque autorisation, et chaque clé MCP, a sa propre clé API, ses réglages, ses plafonds et ses statistiques. Couper un assistant ne touche pas les autres.
• Jetons : jamais dans l'URL, conservés uniquement sous forme d'empreinte. Un jeton de renouvellement réutilisé révoque toute l'autorisation.
• Données : aucune adresse n'est conservée en clair. Les lots suivent les mêmes règles de chiffrement et de conservation que ceux du tableau de bord.
• Journal : chaque appel d'outil apparaît dans les statistiques de la clé (endpoint /mcp/<outil>), sans adresse pour la recherche BtoB.

Suivre et révoquer

Intégrer → Connecteurs → Assistants IA liste les applications connectées (application, adresse de retour, droits, date d'autorisation, dernier appel), les clés MCP et l'activité des 30 derniers jours.

• Révoquer une application coupe son accès immédiatement : jetons effacés, clé dédiée révoquée.
• Révoquer la clé dédiée depuis Clés API a le même effet.
• Supprimer votre compte YesWeCheck révoque toutes les autorisations.

Dépannage

Symptôme	Que faire
L'assistant redemande la connexion en boucle	Révoquez l'application dans Assistants IA, puis reconnectez-vous en cochant la recherche BtoB si vous l'utilisez
Bouton Autoriser absent sur la page d'autorisation	Seuls le propriétaire et les administrateurs de l'organisation autorisent une application ; demandez-leur, ou Changer de compte
SCOPE_REQUIRED sur find_btob_email	Reconnectez l'application en cochant la recherche d'email professionnel, ou activez Finder BtoB pour les agents IA sur la clé
API_KEY_BUDGET_EXCEEDED	Relevez le plafond de la clé dédiée dans Clés API
Aucune adresse vérifiée en SMTP	Le SMTP est désactivé sur la connexion : modifiez la clé dédiée dans Clés API
Un lot n'apparaît pas dans list_batch_jobs	Seuls les lots lancés par un assistant y figurent