MCP tools for AI agents
VerifAi exposes its verification engine as Model Context Protocol (MCP) tools, so an AI agent can validate, enrich, clean and explain email addresses directly — no glue code. The tools run the exact same authentication, plan, rate-limit and billing path as the REST API, so a verdict and its price are identical no matter which surface you call.
The tools
| Tool | What it does | Cost | Returns |
|---|---|---|---|
validate_email | Verify one address: syntax, MX, SMTP mailbox, catch-all, disposable, role. | 1 credit for a definitive answer. Unknown and syntax-only are free. Catch-all is charged once. | Verdict, per-check results, evidence, depth_requested vs depth_applied. |
enrich_contact | Normalize a contact from any fields you have (email, name, phone, address, company, website). | Free. | Structured, canonical fields with per-field provenance and a completeness score. |
clean_list | Clean a whole CSV list asynchronously; poll for status and download the cleaned file. | Per definitive result, same rules as validate_email. | A job_id and poll URL; on completion, per-verdict counts and a result_url. |
explain_result | Explain, in plain language, why an address got its verdict. | Free (reads an existing result). | A readable summary, the chronological on-the-wire sequence, and the provenance of each check. |
find_email | Find a named person’s work email from first name, last name and company domain. Returns the most likely address, a confidence, the pattern and how it was derived (corpus / learned_cache / generic), whether it was probe-verified, and a plain reason. Catch-all domains return a best guess marked unverified, never a false positive. | Bundled — 0 credits. Gated by plan and the shared per-key rate limit. | email, found, verified, confidence, pattern, pattern_source, candidates_probed, reason. |
Authenticating — pass your API key as an argument
Every tool takes your VerifAi api_key as a call argument. VerifAi identifies your tenant from that key alone: two customers can call the same tool and each sees only their own records, credits and plan. No tool accepts a tenant identifier — identity is never taken from the caller, only resolved from the key.
Security — use a dedicated key per agent. An API key passed as a tool argument may be retained in an agent’s conversation context or logs. Issue a separate key for each agent integration under Settings → API Keys, and revoke it there the moment an integration is retired or a context may have been exposed. Revocation is instant and affects only that key.
Rate limits & depth
MCP calls share the same per-key, per-minute rate limit as the REST API (Free 10 · Clean 100 · Clean Pro 600 · Always Clean 1200 · Data Ops 3000) — a key at its limit is limited whichever surface it used. Requesting more depth than your plan allows degrades gracefully rather than erroring, and the response reports depth_requested and depth_applied.
clean_list — two modes
Start a job by passing csv (raw CSV text with a header row; the email column is auto-detected) and, optionally, list_name and depth. You get back a job_id. Poll by calling clean_list again with just that job_id; when status is completed the response includes per-verdict counts and a result_url for the cleaned CSV. The job is the same one the REST API and the web uploader create, and it fires the same signed job.completed webhook.
The REST equivalent, GET /v1/jobs?id=<job_id>, takes the job id as a query parameter rather than a path segment (/v1/jobs/<id>). That is deliberate: the platform routes an app’s HTTP endpoints by a fixed path and does not expose trailing path segments to the handler, so a resource id must travel as a query parameter. Over MCP you never see this — you just pass job_id.
Why explain_result matters
Most verification tools return an opaque code. explain_result gives an agent the reasoning: the sequence of what was observed on the wire and where each fact came from, in language a person can act on. Validate first, then explain the address you care about.
keep_clean
Enrol a list for continuous hygiene from an agent. keep_clean takes api_key, list_id, an action (register / unregister / status) and, for register, a cadence of 30, 60 or 90 days. It shares the same authentication, tenant scoping and rate limiter as the other tools. Re-checks of records already under management are free and unlimited, and registration deducts no credits — this is the verb that turns a one-off clean into an ongoing subscription. It is the agent-facing twin of POST /v1/hygiene.