Skip to content

MCP server

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. Agents are available starting on the Starter plan; the Free plan cannot create one. 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 Desktop

Settings, then Connectors, then Add custom connector, with the URL https://mcp.pricklymails.com/mcp. 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 api_key argument, a pm_live_ or pm_test_ key from your account, either pasted into the conversation or minted with create_api_key.
  • 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. 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. Chunks after the first always run the plan's full check set. 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 identity (its OAuth session) is separate from the verification credential (an API key): the agent authenticates over OAuth, then verifies using your account's API keys, the same split the REST API itself uses between a dashboard session and a pm_ key.