prospectapis-mcp 0.2.5 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,30 @@ All notable changes to `prospectapis-mcp` are documented here. The format follow
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-25
+
+### Added
+
+- `email_verify_stats` and `email_outcomes_report`: your verification mix, and bounced or delivered reports (a charged valid you report bounced within 30 days is credited back).
+- `email_verify_job_create`, `email_verify_job_get`, `email_verify_job_results`, `email_verify_job_stop`: bulk verification jobs of up to 50,000 addresses with free retries for slow servers, list sampling (`sample`) and list monitoring (`monitor_days`).
+- `email_find`: a person's work address from name and domain, $0.02 only when found.
+- `email_domain_check`: what DNS and our recent checks know about a domain, free.
+- `email_verify_calibration`: measured bounce rate per score band, free.
+- `email_clean_list`: sort up to 1,000 addresses into keep, review and remove with quick checks.
+- `email_verify` takes `depth: "quick"` ($0.001 per address, no mail server contacted). Twenty-five tools.
+
+## [0.3.0] - 2026-10-25
+
+### Added
+
+- `email_verify` (`POST /v1/email/verify`): check 1 to 25 email addresses for deliverability. Each result carries `status` (valid, invalid, catch-all or unknown), `reason`, `charged`, `flags`, `smtp_code` and `catch_all_tier`. A valid or invalid result costs $0.004; catch-all and unknown results are free. When the balance covers only some addresses, the rest come back `unknown` with reason `not_checked_insufficient_credits`, free. Fifteen tools.
+
+### Changed
+
+- Pricing: every account starts with a free $1 balance (no card, no monthly reset) that each paid call draws from at its own price. The 100 free funding records a month are gone, so tool descriptions, the server instructions, the playbooks and the README no longer promise them. Watchlist deliveries cost $0.02 per delivered record from the balance.
+- `pricing_get` and `account_balance` descriptions name the new fields (the signup balance, the email verification price and which statuses are charged).
+- The 402 hint reads "out of credits for this call".
+
 ## [0.2.5] - 2026-10-20
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # prospectapis-mcp
 
-prospectapis-mcp is the MCP server for ProspectAPIs (https://prospectapis.com), for sales and prospecting teams and the AI agents they run in Claude Code, Claude Desktop, Cursor and other MCP clients. It gives your agent fourteen tools over the ProspectAPIs API: search funding rounds by date, round, amount, company, investor and country, get new matching rounds pushed to your webhook, and order a cited research brief on any company or person. Funding records carry the public announcement URL when there is one. Records cost $0.02 each after 100 free a month, a completed brief costs $0.15, and there are no seats, no subscription and no card to sign up. It needs Node.js 22 or later.
+prospectapis-mcp is the MCP server for ProspectAPIs (https://prospectapis.com), for sales and prospecting teams and the AI agents they run in Claude Code, Claude Desktop, Cursor and other MCP clients. It gives your agent twenty-five tools over the ProspectAPIs API: search funding rounds by date, round, amount, company, investor and country, get new matching rounds pushed to your webhook, verify, find and bulk-check email addresses, report what bounced, and order a cited research brief on any company or person. Funding records carry the public announcement URL when there is one. Every account starts with a free $1 balance and no card: records cost $0.02, an email check $0.004 and a completed brief $0.15, with no seats and no subscription. It needs Node.js 22 or later.
 
 Install (Claude Code): `claude mcp add prospectapis -e PROSPECTAPIS_API_KEY=pa_live_... -- npx -y prospectapis-mcp`
 
@@ -10,10 +10,16 @@ Website: https://prospectapis.com/mcp
 
 | Tool | Endpoint | Cost |
 |---|---|---|
-| `funding_search` | `GET /v1/funding` | $0.02 per record returned, after 100 free records a month; no match is free |
+| `funding_search` | `GET /v1/funding` | $0.02 per record returned; no match is free |
 | `funding_get` | `GET /v1/funding/:id` | $0.02 when found; a missing id is free |
 | `research_submit` | `POST /v1/research` | one research at `research_price_usd` (see `account_balance`), charged only when the brief completes; refunded on failure |
 | `research_get` | `GET /v1/research/:id` | free; poll until `status` is `completed` or `failed` |
+| `email_verify` | `POST /v1/email/verify` | $0.004 per `valid` or `invalid` result; `catch-all` and `unknown` are free; 1 to 25 addresses a call |
+| `email_verify_stats` | `GET /v1/email/verify/stats` | free |
+| `email_outcomes_report` | `POST /v1/email/outcomes` | free; 1 to 100 outcomes a call |
+| `email_verify_job_create` | `POST /v1/email/verify/jobs` | free to start; $0.004 per `valid` or `invalid` result as it is checked; up to 50,000 addresses |
+| `email_verify_job_get` | `GET /v1/email/verify/jobs/:id` | free |
+| `email_verify_job_results` | `GET /v1/email/verify/jobs/:id/results` | free; 1,000 a page |
 | `watchlist_create`, `watchlist_list`, `watchlist_get`, `watchlist_deliveries`, `watchlist_test`, `watchlist_delete` | `/v1/watchlists` | free to manage; a delivered event costs one record, only when your webhook answers 2xx |
 | `account_balance` | `GET /v1/account` | free |
 | `feedback_send` | `POST /v1/feedback` | free; reports a bug, wrong field or missing capability to the team (10 an hour per key) |
@@ -29,6 +35,10 @@ Website: https://prospectapis.com/mcp
 `context` (your own product, at most 1,000 characters) and `purpose` (`account_research`, `pre_call` or
 `outreach`). It returns a `research_id` at once; a brief takes 20 to 90 seconds.
 
+`email_verify` takes `emails`, a list of 1 to 25 addresses. Each result has `status` (`valid`, `invalid`,
+`catch-all` or `unknown`), `reason`, `reason_text`, `score` (0 to 100), `recommendation` (`send`, `send_with_caution`, `retry_later` or `do_not_send`), `charged`, `flags`, `smtp_code` and `catch_all_tier`. If the balance covers only
+some addresses, the rest come back `unknown` with reason `not_checked_insufficient_credits` and are not charged.
+
 ## Configure
 
 | Variable | Required | Default |
@@ -56,7 +66,7 @@ Claude Code: `claude mcp add prospectapis -e PROSPECTAPIS_API_KEY=pa_live_... --
 
 **Where does the funding data come from?** Records carry the public announcement URL when there is one.
 
-**What is free?** 100 funding records a month, any search that matches nothing, watchlist management, and the balance, pricing and version tools.
+**What is free?** A $1 balance when you sign up (about 50 funding records, 250 email checks or 6 research briefs), any search that matches nothing, catch-all and unknown email results, watchlist management, and the balance, pricing and version tools.
 
 **Which clients work?** Claude Code, Claude Desktop, Cursor and any client that reads an mcpServers config, through `npx -y prospectapis-mcp`.
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "prospectapis-mcp",
-  "version": "0.2.5",
+  "version": "0.4.0",
   "mcpName": "io.github.ProspectAPIs/prospectapis-mcp",
-  "description": "MCP server for ProspectAPIs: search funding rounds, run paid prospect research briefs, manage funding watchlists, read your balance and the live price list.",
+  "description": "MCP server for ProspectAPIs: search funding rounds, verify email addresses, run paid prospect research briefs, manage funding watchlists, read your balance and the live price list.",
   "type": "module",
   "bin": {
     "prospectapis-mcp": "src/index.js"

package/src/playbooks.js

@@ -20,8 +20,8 @@ const NEWLY_FUNDED = `# Newly funded prospects
 
 Build a short list of companies that just raised, worth reaching out to while the round is fresh.
 
-1. \`account_balance\` first. Each funding record returned costs $0.02 after 100 free a month, so know what is left
-   before you pull pages.
+1. \`account_balance\` first. Each funding record returned costs $0.02, drawn from your balance (a new account starts
+   with $1, about 50 records), so know what is left before you pull pages.
 2. \`funding_search\` with a tight window and the filters that describe the buyer: \`since\` (for example the last 30
    days), \`round\` (such as \`seed,series_a\`), \`country\`, and \`min_amount_usd\` or \`max_amount_usd\`. Start with
    \`limit\` 10 to 25. A search that matches nothing costs nothing, so narrow before you widen.
@@ -45,7 +45,7 @@ A cited brief on one company or person before a call or a first email.
 2. It returns \`research_id\` at once. The brief takes 20 to 90 seconds: call \`research_get\` with that id every 10 to 15
    seconds until \`status\` is \`completed\` or \`failed\`. Polling is free.
 3. A brief is charged only when it completes, at the \`research_price_usd\` that \`account_balance\` reports, and refunded
-   in full if it fails. Free records do not apply to research.
+   in full if it fails.
 4. Every field in \`result\` is \`{value, sources, confidence}\`. Quote the sources with the claims you use, and say when
    a field came back empty rather than filling the gap.
 `;

package/src/server.js

@@ -1,5 +1,5 @@
 // MCP server wiring: one registered tool per catalog entry, each a single
-// authenticated request (a GET, or a POST with a JSON body for research_submit)
+// authenticated request (a GET, or a POST with a JSON body for research_submit and email_verify)
 // against the ProspectAPIs REST API. Exported as a factory
 // (createServer) so tests inject a fake fetch and a host could inject auth.
 
@@ -15,11 +15,13 @@ export const { version: VERSION } = createRequire(import.meta.url)("../package.j
 export const DEFAULT_BASE_URL = "https://api.prospectapis.com";
 export const DEFAULT_TIMEOUT_MS = 30000;
 export const SIGNUP_URL = "https://prospectapis.com/signup?utm_source=mcp";
-export const TOP_UP_URL = "https://prospectapis.com/dashboard/credits?utm_source=mcp";
+export const TOP_UP_URL = "https://prospectapis.com/dashboard/billing?utm_source=mcp";
 
 export const INSTRUCTIONS =
-  "ProspectAPIs MCP server: funding rounds data and prospect research briefs. funding_search and funding_get cost $0.02 per record returned, " +
-  "after 100 free records per calendar month; a search that matches nothing costs nothing. account_balance, pricing_get and api_version are free. " +
+  "ProspectAPIs MCP server: funding rounds data, email verification and prospect research briefs. Every account starts with a free $1 balance " +
+  "(no card, no monthly reset), and each paid call draws from it at its own price. funding_search and funding_get cost $0.02 per record returned; " +
+  "a search that matches nothing costs nothing. email_verify checks 1 to 25 addresses for $0.004 per valid or invalid result; catch-all and " +
+  "unknown results are free. account_balance, pricing_get and api_version are free. " +
   "Use filters (dates, round, amount, domain, investor, country) to keep result sets small, and call account_balance before a large paged search. " +
   "research_submit starts a cited brief on one prospect and returns a research_id; poll research_get (free) until it is completed or failed. " +
   "A research is charged only when it completes, at the research_price_usd account_balance reports. " +
@@ -28,8 +30,7 @@ export const INSTRUCTIONS =
 
 export function hintFor(status) {
   if (status === 401) return " (missing or invalid API key: set PROSPECTAPIS_API_KEY to a key from the dashboard)";
-  // research never draws on free records, so the hint does not promise any (PR #23 review, L4)
-  if (status === 402) return ` (not enough credit for this call; the body says what it costs: top up at ${TOP_UP_URL})`;
+  if (status === 402) return ` (out of credits for this call; the body says what it costs: top up at ${TOP_UP_URL})`;
   if (status === 400) return " (an argument was rejected: the body says which one)";
   if (status === 404) return " (not found: the id may be wrong, or the record is not published)";
   if (status === 429) return " (rate limited: wait a few seconds and retry)";

package/src/tools.js

@@ -6,9 +6,9 @@
 //     except `{name}` placeholders in `path`, which are interpolated into the
 //     URL and removed from the query string;
 //   - `body: true` sends the arguments as a JSON body instead of a query
-//     string (research_submit, a POST);
+//     string (research_submit and email_verify, POSTs);
 //   - `write: true` marks a tool that changes state or spends credits
-//     (research_submit starts a paid job); the server turns `write` into MCP's
+//     (research_submit starts a paid job, email_verify spends credits); the server turns `write` into MCP's
 //     readOnlyHint, so every other tool is read-only;
 //   - `auth: false` marks the tools the API serves without a key (pricing_get, api_version);
 //   - `title` is the human name a client shows instead of the raw tool name;
@@ -48,7 +48,7 @@ export const TOOLS = [
     write: false,
     format: { min_amount_usd: formatAmount, max_amount_usd: formatAmount },
     description:
-      "Search funding rounds (venture rounds, debt, grants, IPOs), newest announcement first. Costs $0.02 per record returned, after 100 free records a month; a search that matches nothing is free. " +
+      "Search funding rounds (venture rounds, debt, grants, IPOs), newest announcement first. Costs $0.02 per record returned, drawn from your balance (every account starts with a free $1); a search that matches nothing is free. " +
       "Page with `cursor`: pass back `next_cursor` exactly as returned; a null `next_cursor` means there are no more matches. Narrow with filters before raising `limit`.",
     shape: {
       since: DATE.describe("Earliest announcement date, inclusive (YYYY-MM-DD)."),
@@ -73,7 +73,7 @@ export const TOOLS = [
     path: "/v1/funding/{id}",
     title: "Get Funding Round",
     write: false,
-    description: "Read one funding record by id. Costs $0.02 when found (free records are used first); a missing id is free.",
+    description: "Read one funding record by id. Costs $0.02 when found; a missing id is free.",
     shape: {
       id: z.string().uuid().describe("The funding record id from a `funding_search` result."),
     },
@@ -92,7 +92,7 @@ export const TOOLS = [
       "a work email, or linkedin_url), or person_name together with company_name. Returns `research_id` at once; the brief takes 20 to 90 seconds, " +
       "so poll research_get every 10 to 15 seconds until `status` is `completed` or `failed`. " +
       "Costs one research at the price account_balance reports as `research_price_usd`, held when you submit, charged only when the brief " +
-      "completes and refunded in full if it fails. Free records do not apply.",
+      "completes and refunded in full if it fails.",
     shape: {
       domain: z.string().min(3).max(253).optional().describe("The company's domain, for example `acme.com`."),
       website_url: URL_ARG.optional().describe("Any http(s) URL on the company's website."),
@@ -125,6 +125,177 @@ export const TOOLS = [
       id: z.string().uuid().describe("The `research_id` from research_submit."),
     },
   },
+  {
+    name: "email_verify",
+    method: "POST",
+    path: "/v1/email/verify",
+    title: "Verify Email Addresses",
+    write: true,
+    body: true,
+    description:
+      "Check whether 1 to 25 email addresses can receive mail. Each result has `status` (valid, invalid, catch-all or unknown), " +
+      "`reason`, `reason_text`, `score` (0 to 100), `recommendation` (send, send_with_caution, retry_later or do_not_send), `charged`, `flags`, `smtp_code`, `catch_all_tier`, `did_you_mean` (a likely domain typo), `mail_provider` and `checked_at`. Costs $0.004 per valid or invalid result, drawn from your " +
+      "balance; catch-all and unknown results are free (pricing_get lists which statuses are charged). When the balance covers only " +
+      "some addresses, the rest come back `unknown` with reason `not_checked_insufficient_credits`, free. " +
+      "`depth: \"quick\"` never contacts the mail server: syntax, disposable and free lists, DNS, parked and new-domain flags " +
+      "and a recently measured catch-all verdict, at $0.001 per address whatever the status; an address that needs a mailbox " +
+      "check comes back `unknown` with reason `not_probed`.",
+    shape: {
+      depth: z.enum(["full", "quick"]).optional().describe("full (default) checks the mailbox; quick is DNS and lists only, $0.001 per address."),
+      emails: z
+        .array(z.union([
+          z.string().min(3).max(254),
+          z.object({ email: z.string().min(3).max(254), first_name: z.string().max(80).optional(), last_name: z.string().max(80).optional() }),
+        ]))
+        .min(1)
+        .max(25)
+        .describe("The addresses to check, 1 to 25 per call. An item may be {email, first_name, last_name} to also check the address against the person's name."),
+    },
+  },
+  {
+    name: "email_domain_check",
+    method: "GET",
+    path: "/v1/email/domain/{domain}",
+    title: "Check Email Domain",
+    idempotent: true,
+    write: false,
+    description:
+      "What is known about one email domain without contacting its mail server: `exists`, `accepts_mail`, `null_mx`, `mx` hosts, " +
+      "`mail_provider`, `spf`, `dmarc`, `disposable`, `free_provider`, `parked`, `domain_age_days`, `new_domain`, `did_you_mean`, " +
+      "and `catch_all` (true or false only when our own check measured it recently, else null) with `catch_all_checked_at`. " +
+      "Free, up to 300 lookups an hour per account.",
+    shape: { domain: z.string().min(3).max(253).describe("A domain name such as example.com.") },
+  },
+  {
+    name: "email_find",
+    method: "POST",
+    path: "/v1/email/find",
+    title: "Find Email Address",
+    write: true,
+    body: true,
+    description:
+      "Find a person's work email from `first_name`, `last_name` and company `domain`. The common patterns are checked in order " +
+      "against the mail server, most common first. Returns `status` (found, catch_all, unknown, not_found), `email`, `pattern`, " +
+      "`score`, `recommendation` and the addresses `checked`. Costs $0.02 only when an address is found; on a catch-all domain " +
+      "it returns the most likely address as `best_guess`, free.",
+    shape: {
+      first_name: z.string().min(1).max(80).describe("The person's first name."),
+      last_name: z.string().max(80).optional().describe("The person's last name."),
+      domain: z.string().min(3).max(253).describe("The company's email domain, such as example.com."),
+    },
+  },
+  {
+    name: "email_verify_calibration",
+    method: "GET",
+    path: "/v1/email/verify/calibration",
+    title: "Email Score Calibration",
+    idempotent: true,
+    write: false,
+    description:
+      "What each verification score band has meant in practice: the measured bounce rate per band from delivery outcomes " +
+      "customers reported over the last 90 days. A band with fewer than 30 reports shows a null rate. Free.",
+    shape: {},
+  },
+  {
+    name: "email_clean_list",
+    method: "POST",
+    path: "/v1/email/clean",
+    title: "Clean Email List",
+    write: true,
+    body: true,
+    description:
+      "Clean a list of up to 1,000 addresses in one call with quick checks (no mail server is contacted): returns `keep`, " +
+      "`review` (role, free, parked, new or typo addresses, with a reason) and `remove` (cannot receive mail), plus `counts`. " +
+      "$0.001 per well-formed address. Run email_verify on the kept addresses you will actually send to.",
+    shape: {
+      emails: z.array(z.string().min(3).max(254)).min(1).max(1000).describe("The addresses to clean, 1 to 1,000."),
+    },
+  },
+  {
+    name: "email_verify_stats",
+    method: "GET",
+    path: "/v1/email/verify/stats",
+    title: "Email Verification Stats",
+    write: false,
+    description:
+      "Your own email verification mix over the last `days` (1 to 90, default 30): `total`, `by_status` (valid, invalid, " +
+      "catch-all, unknown), `charged`, `served_from_cache`, `catch_all_share` and `unknown_share`. Free.",
+    shape: {
+      days: z.number().int().min(1).max(90).optional().describe("Window in days, 1 to 90 (default 30)."),
+    },
+  },
+  {
+    name: "email_outcomes_report",
+    method: "POST",
+    path: "/v1/email/outcomes",
+    title: "Report Email Outcomes",
+    write: true,
+    body: true,
+    description:
+      "Report what happened when you sent: `bounced` or `delivered`, 1 to 100 addresses per call. A bounce you report makes " +
+      "your later email_verify checks of that address come back invalid (reason `reported_bounce`); a delivered report on a " +
+      "catch-all address raises its score. Returns `stored`. Free.",
+    shape: {
+      outcomes: z
+        .array(z.object({ email: z.string().min(3).max(254), outcome: z.enum(["bounced", "delivered"]) }))
+        .min(1)
+        .max(100)
+        .describe("Each address and what happened when you sent to it."),
+    },
+  },
+  {
+    name: "email_verify_job_create",
+    method: "POST",
+    path: "/v1/email/verify/jobs",
+    title: "Start Email Verification Job",
+    write: true,
+    body: true,
+    description:
+      "Check up to 50,000 addresses in the background. Returns 202 with a job `id`; poll email_verify_job_get. A slow or " +
+      "greylisting server is retried about 5, 15 and 30 minutes later, free. Each valid or invalid result costs $0.004 as " +
+      "it is checked; catch-all and unknown are free. An optional https `callback_url` gets one signed POST when the job " +
+      "completes (verify with the returned `secret`). At most 5 jobs run at once per account.",
+    shape: {
+      sample: z.number().int().min(10).max(50000).optional().describe("Check only a random sample of this many addresses; the job then reports estimated shares for the whole list."),
+      monitor_days: z.number().int().min(7).max(90).optional().describe("Check the whole list again this many days after each run, billing each definite result again; the callback reports what changed."),
+      emails: z.array(z.string().min(1).max(254)).min(1).max(50000).describe("The addresses, 1 to 50,000."),
+      callback_url: z.string().url().max(2048).optional().describe("An https URL to POST to when the job completes."),
+    },
+  },
+  {
+    name: "email_verify_job_get",
+    method: "GET",
+    path: "/v1/email/verify/jobs/:id",
+    title: "Get Email Verification Job",
+    write: false,
+    description: "A job's `status` (queued, running, completed), `total`, `done`, `charged_count` and `amount_usd`. Free.",
+    shape: { id: z.string().uuid().describe("The job `id` from email_verify_job_create.") },
+  },
+  {
+    name: "email_verify_job_results",
+    method: "GET",
+    path: "/v1/email/verify/jobs/:id/results",
+    title: "Get Email Verification Job Results",
+    write: false,
+    description:
+      "A job's results in input order, up to 1,000 a page (`limit`), from `cursor`; `next_cursor` is null on the last page. " +
+      "An address not yet checked shows status `pending`. Free.",
+    shape: {
+      id: z.string().uuid().describe("The job `id`."),
+      cursor: z.number().int().min(0).optional().describe("Start at this position (0-based)."),
+      limit: z.number().int().min(1).max(1000).optional().describe("Results per page, 1 to 1,000 (default 1,000)."),
+    },
+  },
+  {
+    name: "email_verify_job_stop",
+    method: "POST",
+    path: "/v1/email/verify/jobs/{id}/stop",
+    title: "Stop Verification Job",
+    body: true,
+    write: true,
+    description: "Turn off a job's monitoring (its regular re-checks); a job still running is cancelled, and what it already checked stays readable. Free.",
+    shape: { id: z.string().uuid().describe("The job id.") },
+  },
   {
     name: "watchlist_create",
     method: "POST",
@@ -135,7 +306,7 @@ export const TOOLS = [
     description:
       "Save a funding-signal alert: a set of funding_search filters plus an https webhook. Each NEW funding event that " +
       "matches is POSTed to the webhook, signed with the returned `secret` (header Prospect-Signature: t=..,v1=HMAC-SHA256). " +
-      "Creating is free; each delivered event costs one record ($0.02, free records first), charged only when the webhook " +
+      "Creating is free; each delivered event costs one record ($0.02), charged only when the webhook " +
       "answers 2xx. The `secret` is shown once. Max 20 active per account.",
     shape: {
       name: z.string().min(1).max(100).describe("A label, such as 'Series A robotics'."),
@@ -210,7 +381,7 @@ export const TOOLS = [
     title: "Get Account Balance",
     idempotent: true,
     write: false,
-    description: "Your credit balance and the free records left this month. Free. Check it before a large paged search.",
+    description: "Your credit balance and the prices you pay (record, research, email verification). Free. Check it before a large paged search.",
     shape: {},
   },
   {
@@ -241,8 +412,9 @@ export const TOOLS = [
     write: false,
     auth: false,
     description:
-      "The live price list: funding records (price per record and free records a month), research (whether it is " +
-      "available and its price per brief) and watchlist deliveries. Free, needs no key. Use it to quote a cost before a large call.",
+      "The live price list: the balance a new account starts with, funding records (price per record), research (whether it is " +
+      "available and its price per brief), email verification (price per check, which statuses are charged and which are free) " +
+      "and watchlist deliveries. Free, needs no key. Use it to quote a cost before a large call.",
     shape: {},
   },
   {