Skip to main content

AI assistants (MCP server)

The YesWeCheck MCP server gives your AI assistant tools to verify addresses and find B2B emails. You talk to it as usual, and it calls YesWeCheck when useful. It applies your account settings (checks, SMTP, validation policy, lists) and uses the same credits.

https://api.yeswecheck.fr/mcp

The protocol is the Model Context Protocol, over the Streamable HTTP transport. Any compatible MCP client can connect to it.

ChatGPTClaudeLe Chat (Mistral)Claude CodeCursorVS Code

What you can ask​

  • "Verify the address [email protected]."
  • "Here are 300 addresses from a trade show: which ones are invalid?"
  • "How many credits would this list cost?" (estimate, nothing is charged)
  • "Find Jane Doe's work email at acme.com."
  • "How is the clean-up I started this morning going?"
  • "How many credits do I have left?"

Install​

Two ways to connect:

  • OAuth (Claude, ChatGPT, Le Chat, Claude Code, Cursor, VS Code): you paste the server address, a YesWeCheck page opens, you choose the permissions and click Approve. No key to copy.
  • API key (scripts, agents, CI, servers without a browser): a dedicated MCP key sent in the Authorization header. See Connect with an API key.

The server address and these same steps are also in the customer area: Integrate → Integrations → AI assistants.

Claude
  1. In Claude (web or Desktop), open the Connectors menu and add a custom connector.
  2. Name it YesWeCheck and paste the server address.
  3. Click Connect: the YesWeCheck page opens; choose the permissions, then Approve.
  4. Enable the connector in the conversation and ask your question.

On a Team or Enterprise plan, the connector must first be added by an owner of the Claude workspace.

Authorise access​

The authorisation page opens on app.yeswecheck.fr; sign in if needed, with your usual methods (password, Google, GitHub, two-factor authentication). It shows the app requesting access and the address you will be sent back to.

SettingDefaultEffect
OrganisationThe one in your session (Switch account for another)The assistant acts for that organisation only
Verify email addressesAlways grantedValidation, batch tracking and credit tools
Find a person's work emailTicked if the app requests itfind_btob_email tool
Mailbox check (SMTP)On1 credit per address checked over SMTP (see Credits)
Daily credit limit500 (empty = no limit)Beyond it, validations with SMTP from this connection are refused until the next day

Only the organisation's owners and admins can authorise an app; a member can only deny.

On authorisation, YesWeCheck creates an API key dedicated to this app, named MCP – <app name>. It carries the chosen settings; its secret is never shown. You find it in API keys, with the MCP · OAuth badge, where you can change its checks, its limit or its IP restrictions as for any key.

The app receives an access token valid for one hour, renewed automatically for 30 days of use. An app inactive for more than 30 days must reconnect.

Connect with an API key​

For a script, a server-side agent or continuous integration, create an MCP key in Integrate → Integrations → AI assistants, Scripts and agents tab: choose SMTP, B2B search and a daily limit. The ywc_live_… secret is shown only once.

One key per agent: it can be revoked on its own, without cutting off your other integrations. A regular API key works too, with its own settings; B2B search is enabled in the key, with the B2B Email Finder for AI agents option (AI agents (MCP) block, off by default).

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

Or, in the project's .mcp.json file, with the key in the YWC_API_KEY environment variable:

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

The server only accepts Authorization: Bearer. A widget-scope key and a dashboard session token are refused (401/403).

The tools​

ToolPurposeCostRead-only
validate_emailVerifies an address1 credit if SMTP and verdict ≠ unknownNo
validate_emails_batchVerifies a list (up to 5,000 addresses)Same, per addressNo
get_batch_jobProgress of a batchFreeYes
get_batch_resultsResults of a batch, page by pageFreeYes
list_batch_jobsBatches started by your assistantsFreeYes
cancel_batch_jobCancels a running batchRefund of addresses without a conclusionNo
find_btob_emailFinds a person's work email1 search from the daily quota, no creditsNo
get_creditsBalance, key limits, B2B quotaFreeYes

Each tool returns a readable summary and a structured output (structuredContent) described by a schema: the assistant reads the fields directly.

validate_email​

InputDescription
emailThe address to verify (320 characters at most)

The output is that of POST /v2/email/validate: result (valid, risky, invalid, unknown), score, finalDecision from your policy, features with the detail of each check active on the key; plus a credits object (used, remaining, unlimited). If a typo is detected, the assistant suggests the corrected address (features.typoCorrection).

To protect the assistant against instructions hidden in third-party data, free text from outside is not passed on: raw response from the mail server (replaced by a fixed message), SPF, DMARC and BIMI records, domain owner. Verdicts, scores and codes are identical to the API.

validate_emails_batch​

InputDescription
emails1 to 5,000 addresses
labelName of the batch in the dashboard (optional)
dry_runtrue: counts the addresses and estimates the credits, without verifying or charging anything

Entries without @ are discarded and duplicates removed (case-insensitive comparison), as when importing a file. Then:

  • up to 25 unique addresses: immediate response, one verdict per address (results), with summary per verdict and credits_used;
  • beyond that: bulk processing starts in the background. The response gives job.job_id and the link to the batch in the dashboard, where it carries the MCP badge. Only one batch at a time per organisation.

Before starting a batch, the server checks that the balance and the key's limit cover the estimate (max_credits); otherwise it refuses without starting anything. In dry_run mode, blocked_by shows what would block it.

get_batch_job​

Input: job_id. Output: status (pending, processing, paused, completed, failed, cancelled), phase, percentage, processed/total, counters per verdict, smtp.downgraded (balance used up along the way: the rest ran without SMTP) and results_ready. One call per minute is enough.

get_batch_results​

InputDescription
job_idBatch identifier
statusFilter on a verdict (optional)
cursornext_cursor from the previous page; absent for the first one
limitPage size, 100 by default, 500 at most

Each row gives email, status, score and reason (the integrations' reasons). next_cursor is null on the last page. CSV and Excel exports and the PDF report remain in the dashboard.

list_batch_jobs and cancel_batch_job​

list_batch_jobs (limit from 1 to 20, 10 by default) lists the batches started by your assistants, newest first; batches imported in the dashboard are not included, and the tracking tools cannot see them.

cancel_batch_job (job_id) stops a running batch: addresses without a billable verdict are refunded, verdicts already obtained remain charged, and the batch results are deleted.

find_btob_email​

InputDescription
first_name · last_nameFirst name and last name
domainThe company's domain, for example acme.com (not a URL, not a consumer email provider)

Likely address formats are tested against the company's mail server until one is confirmed, in 40 seconds at most. outcome is:

outcomeMeaning
foundMailbox confirmed: email and its format (pattern, for example first.last)
accept_allThe domain accepts all addresses: no mailbox can be confirmed
not_foundNo tested format was accepted
incompleteTime limit reached before the tests finished; a new search starts from scratch

A search uses one unit of the organisation's B2B quota (20 per day, shared with the dashboard), never a credit. A consumer domain or one without a mail server is refused before the quota. An organisation's searches run one at a time; the addresses found also appear in the B2B search history in the dashboard.

The tool is only available if B2B search is granted to the connection (box ticked on authorisation, or the key's B2B Email Finder for AI agents option).

get_credits​

No input. Returns the organisation's balance (balance, or unlimited), the key's usage for the day and the month with its limits, the SMTP state on the key and the day's B2B quota (finder).

Credits and quotas​

The rules are those of the API: see Credits.

ActionCost
Validation with SMTP, verdict valid, risky or invalid1 credit
Validation with SMTP, verdict unknown0
Validation without SMTP0
dry_run, batch tracking, results, get_credits0
find_btob_email1 search from the B2B quota (20 per day per organisation)

SMTP is decided by the connection (setting on authorisation, or key configuration), never by the assistant. The connection's daily limit caps what an assistant can spend, even if your balance is higher.

Limits​

ItemLimit
Addresses per validate_emails_batch call5,000 (25 for an immediate response)
Running batches1 per organisation, all channels combined
Calls per keySame per-key limits as the API: every MCP request counts, and every address in an immediate response counts as a validation call
Immediate responseNo address starts after 30 seconds; the remaining ones come out unknown, with no charge
B2B search40 seconds, one at a time per organisation, 20 per day
Request body2 MB

Errors​

Authentication responds over HTTP:

ResponseCause
401 with WWW-AuthenticateToken or key missing, expired or revoked. The OAuth client restarts the authorisation
403 insufficient_scopeThe tool requires a permission that was not granted (B2B search); the client offers to reconnect with that permission
403widget-scope key, IP outside the key's restrictions
429Too many requests from the same IP

A tool's errors arrive in its result (isError: true), in the form CODE: message, followed by Retry after N seconds. when waiting is enough:

CodeCause
INSUFFICIENT_CREDITSBalance used up for a validation with SMTP
API_KEY_BUDGET_EXCEEDEDThe connection's daily or monthly limit reached
RATE_LIMITEDThe key's call limit, or a B2B search already running
QUOTA_EXCEEDEDThe day's B2B quota used up (reset at midnight UTC)
SCOPE_REQUIREDB2B search not granted to this connection
BATCH_ALREADY_RUNNINGA batch is already running in the organisation
BATCH_NOT_READYResults requested before the batch finished
RESULTS_EXPIREDResults deleted (retention period or cancellation)
NOT_FOUNDUnknown batch, or not started by an assistant of this organisation
INVALID_STATEBatch that can no longer be cancelled
INVALID_INPUTInput refused (address, domain, empty list)
FORBIDDENRefused by the key's protection rules
INTERNAL_ERRORInternal error; try again later

Nothing is charged on an error.

Security​

  • One identity per app: each authorisation, and each MCP key, has its own API key, settings, limits and statistics. Cutting off one assistant does not affect the others.
  • Tokens: never in the URL, stored only as a hash. A reused refresh token revokes the whole authorisation.
  • Data: no address is stored in plain text. Batches follow the same encryption and retention rules as those in the dashboard.
  • Log: every tool call appears in the key's statistics (endpoint /mcp/<tool>), without the address for B2B search.

Monitor and revoke​

Integrate → Integrations → AI assistants lists the connected apps (app, return address, permissions, authorisation date, last call), the MCP keys and the activity over the last 30 days.

  • Revoke an app to cut off its access immediately: tokens erased, dedicated key revoked.
  • Revoking the dedicated key from API keys has the same effect.
  • Deleting your YesWeCheck account revokes all authorisations.

Troubleshooting​

SymptomWhat to do
The assistant keeps asking you to reconnectRevoke the app in AI assistants, then reconnect, ticking B2B search if you use it
No Approve button on the authorisation pageOnly the organisation's owner and admins can authorise an app; ask them, or Switch account
SCOPE_REQUIRED on find_btob_emailReconnect the app, ticking work email search, or turn on B2B Email Finder for AI agents on the key
API_KEY_BUDGET_EXCEEDEDRaise the dedicated key's limit in API keys
No address verified over SMTPSMTP is turned off on the connection: edit the dedicated key in API keys
A batch does not appear in list_batch_jobsOnly batches started by an assistant are listed