Skip to content

MCP server

Connect an AI agent to PricklyMails over the Model Context Protocol and verify email deliverability as a single tool call, no glue code.

PricklyMails runs a remote Model Context Protocol (MCP) server, so an AI agent (Claude, for example) can verify email addresses as a tool instead of you wiring the REST API by hand. It is hosted at https://mcp.pricklymails.com/mcp.

Create an agent first

Connecting a client requires a scoped agent, created from the dashboard's Agents page. The Free plan creates one agent, restricted to single-address verification and reading results; every paid plan can grant an agent any scope. The scopes you grant an agent govern what a connected client may do through it, and you can revoke the agent at any time to cut off access immediately.

Connect Claude

In Claude or Claude Desktop, open Customize then Connectors, click + Add, then Add custom connector, with the URL https://mcp.pricklymails.com/mcp. On a Team or Enterprise plan, an owner adds it once for the organization, from Organization settings then Connectors. Authentication is OAuth 2.1: you sign in, then approve one of your agents on the consent screen. No API key is ever pasted into the connector configuration.

Available tools

Verification:

  • verify_email: verify one address. Takes an optional api_key argument, a pm_live_ or pm_test_ key, to bill and scope the call against that key's own account; without it, the verification bills the account you connected.
  • get_verification: fetch a previous job's result by UUID.

Bulk verification:

  • submit_batch: submit up to 4096 emails for bulk verification, billed per unique valid address. A batch holds at least 20 distinct valid addresses; verify fewer with verify_email. Optionally pass checks, the checks to run; without it, the batch runs every check your plan allows. Optionally pass custom_ids, one client reference per email (index-aligned with emails), echoed back verbatim in get_batch_results so you can map a result to your own input row without relying on order. Use your own row identifier, never the email address or other PII: the raw email is never stored.
  • append_batch_emails: append another chunk to an open batch (one created with final: false) to grow a list past a single request. Takes the same optional checks as submit_batch: pass the same ones on every chunk so the whole batch runs one check set. The chunk that closes the batch is refused while the batch would hold fewer than 20 distinct valid addresses, and the batch stays open. Accepts the same optional custom_ids as submit_batch, aligned with this chunk's emails.
  • get_batch: fetch a batch's status, progress, and aggregated results by UUID.
  • get_batch_results: fetch the per-email results for a batch. Each row carries custom_id, the client reference supplied at submit for that email (if any).
  • list_batches: list the caller's batches, newest first.

API keys:

  • create_api_key: mint an API key on your account. Requires the api_keys:create scope.
  • list_api_keys: list the caller's keys with their scopes and enabled checks. Requires api_keys:read.
  • revoke_api_key: revoke a key by UUID, idempotent on repeat. Requires api_keys:revoke.

Webhooks:

  • create_webhook: register a job-completion webhook, returning its signing secret once. Requires webhooks:create.
  • list_webhooks: list the caller's webhook endpoints. Requires webhooks:read.
  • get_webhook: fetch one endpoint by UUID. Requires webhooks:read.
  • update_webhook: update an endpoint's url, events, description, or status. Requires webhooks:update.
  • delete_webhook: delete an endpoint by UUID, idempotent on repeat. Requires webhooks:delete.

Account:

  • check_balance: read the token wallet balance, average daily spend, and active plan. Requires billing:read.
  • list_transactions: read the wallet ledger, newest first. Requires billing:read.
  • list_jobs: list the caller's standalone verification jobs, newest first. Requires results:read.
  • get_usage: read the verification usage overview over the default window. Requires usage:read.
  • get_pricing: read the public plan grid, top-up pricing, and per-check costs. No scope needed.

Scopes

The server advertises twelve 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, and webhooks:delete. Grant an agent only the scopes matching the tools you want it to use.

Billing and credentials

A verification run through verify_email bills your token wallet exactly like the REST API; a pm_test_ key runs the deterministic sandbox and is never billed. The agent's OAuth session is enough to verify: verify_email, get_verification, submit_batch and append_batch_emails bill the connected account's wallet, within the scopes you granted the agent. Pass api_key on one of those calls to bill another account you hold a pm_ key for instead, or a pm_test_ key to stay in the sandbox.