prospectapis-mcp 0.2.5 → 0.3.0

package/CHANGELOG.md

@@ -6,6 +6,18 @@ All notable changes to `prospectapis-mcp` are documented here. The format follow
 
 ## [Unreleased]
 
+## [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 fifteen 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 email addresses, 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,11 @@ 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 |
 | `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 +30,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`, `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 +61,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.3.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,26 @@ 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`, `charged`, `flags`, `smtp_code` and `catch_all_tier`. 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.",
+    shape: {
+      emails: z
+        .array(z.string().min(3).max(254))
+        .min(1)
+        .max(25)
+        .describe("The addresses to check, 1 to 25 per call."),
+    },
+  },
   {
     name: "watchlist_create",
     method: "POST",
@@ -135,7 +155,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 +230,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 +261,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: {},
   },
   {