How do I use Cold Leads MCP server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Cold Leads MCP server verify sarah@acme.com and check if it's catch-all" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Cold Leads MCP server

by anttka4cz

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

Cold Leads MCP server

Model Context Protocol server for Cold Leads, the B2B outreach CRM. It lets AI agents in MCP clients that can start a local stdio server (Claude Desktop, Claude Code, Cursor, Windsurf, VS Code) verify e-mail addresses and look up contacts in your own Cold Leads workspace — and, when there is no API key yet, ask the human owner to approve a subscription.

npx -y github:anttka4cz/mcp-server-coldleads

The package is not on npm; npx installs and builds it straight from GitHub.

Tools

Tool	What it does	Cost
`verify_email`	Verification of one address: syntax, disposable domain, role account and MX records, plus an SMTP mailbox and catch-all check when Cold Leads can open an SMTP connection to the recipient's mail server (otherwise `reasons` contains `smtp_unreachable` and `catch_all` is `null`). Returns `valid`, `risky` or `invalid`. Answers within 5 seconds.	1 credit
`search_leads`	Contacts already in your Cold Leads CRM for a company domain, with an optional role keyword: e-mail, name, company, stage, tags, verification status and a `do_not_contact` flag. Cold Leads has no third-party lead database.	free
`provision_account_and_get_payment_link`	For agents without a key: creates a pending account for the human owner and returns a Stripe payment link for the Business plan. The human decides and pays.	—
`check_provisioning_status`	After the owner paid: returns the API key exactly once (with the `claim_token`). The server starts using it immediately.	—

Responses are compact JSON in a text block, for example for an address whose mailbox could not be checked:

{"status":"success","email":"jane.doe@gmail.com","validity":"valid","catch_all":null,"score":75,"reasons":["smtp_unreachable"],"disposable":false,"role_account":false}

Errors come back as tool results with isError: true, for example {"status":"error","error":"rate_limited","message":"…","http_status":429,"retry_after_seconds":60}.

Related MCP server: Email Verifier MCP Server

Requirements

A Cold Leads secret API key (sk_…) from Settings → API keys. The API is included in the Business plan (10,000 verification and API credits a month; extra packs available).
Node.js 20 or newer (CI tests 20 and 22).
No key yet? Start the server without one and let your agent call provision_account_and_get_payment_link — see Agent onboarding.

Setup

Claude Desktop

claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "coldleads": {
      "command": "npx",
      "args": ["-y", "github:anttka4cz/mcp-server-coldleads"],
      "env": { "COLDLEADS_API_KEY": "sk_your_secret_key" }
    }
  }
}

Cursor / Windsurf

~/.cursor/mcp.json (Cursor) or ~/.codeium/windsurf/mcp_config.json (Windsurf) — the same mcpServers block as above.

Claude Code

claude mcp add coldleads --env COLDLEADS_API_KEY=sk_your_secret_key -- npx -y github:anttka4cz/mcp-server-coldleads

VS Code

.vscode/mcp.json:

{
  "servers": {
    "coldleads": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "github:anttka4cz/mcp-server-coldleads"],
      "env": { "COLDLEADS_API_KEY": "sk_your_secret_key" }
    }
  }
}

Hosted endpoint (no install)

Clients that support remote servers with custom headers can connect directly:

{
  "mcpServers": {
    "coldleads": {
      "url": "https://coldleads.app/api/mcp",
      "headers": { "Authorization": "Bearer sk_your_secret_key" }
    }
  }
}

The endpoint speaks MCP Streamable HTTP (JSON-RPC 2.0 over POST, protocol versions 2024-11-05 to 2025-11-25) and rejects requests without a key with HTTP 401. It offers search_leads and verify_email; the onboarding tools are only in this stdio server. Clients that support remote servers only with OAuth (for example claude.ai custom connectors) cannot use it, because it accepts only an API key; use this stdio server in a desktop client instead.

Docker

docker build -t coldleads-mcp-server .
docker run -i --rm -e COLDLEADS_API_KEY=sk_your_secret_key coldleads-mcp-server

Configuration

Variable	Default	Purpose
`COLDLEADS_API_KEY`	—	Secret API key (`sk_…`). Optional at start-up: without it the server still starts, lists tools and can run agent onboarding.
`COLDLEADS_API_BASE`	`https://coldleads.app`	API base URL (for local development against a Cold Leads dev server).

Agent onboarding without a key

The agent calls provision_account_and_get_payment_link with the owner's e-mail.
It shows the returned checkout_url to the human. The human reviews the plan and price on the secure Stripe page and decides whether to pay. The API gives the agent no way to pay, and the agent is told never to open or pay the link.
The agent polls check_provisioning_status with session_id and claim_token every 15–30 seconds.
After payment the first call returns api_key once; this server switches to it immediately. Store it as COLDLEADS_API_KEY for the next start.
The owner receives an e-mail to open the Cold Leads web app, where they can manage the subscription or rotate the key.

Only a request that carries the claim_token can collect the key; a status lookup without it never returns the key.

Responsible use

A verified address is not consent. You need a lawful basis to contact each person.
Never e-mail leads with do_not_contact: true (opted out, bounced or on the do-not-contact list).
Limits: 120 requests per minute per key; each verification costs 1 credit.

Development

npm ci
npm run build
npm test                      # schema, server and stdio child-process tests
COLDLEADS_API_KEY_FILE=path/to/key COLDLEADS_API_BASE=http://localhost:3000 node scripts/smoke.mjs   # live checks

License

Available Tools

4 tools

check_provisioning_statusCheck the owner's payment and get the API keyA

Checks an account created with provision_account_and_get_payment_link. Returns status pending_payment, active, expired or suspended. When active, the first call with the claim_token returns api_key exactly once: store it securely as COLDLEADS_API_KEY and send it as Authorization: Bearer . Poll every 15–30 seconds while pending_payment.

ParametersJSON Schema

Name	Required	Description	Default
`session_id`	Yes	session_id returned by provision_account_and_get_payment_link.
`claim_token`	Yes	claim_token returned by provision_account_and_get_payment_link.

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds substantial behavior beyond the annotations: the api_key is returned exactly once on the first call with claim_token, must be stored securely, and is used as a Bearer token. This one-time-secret semantics is critical and is consistent with idempotentHint=false, which the description effectively explains.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four tight sentences with zero filler: purpose and status values first, then the critical one-time key behavior, then polling cadence. Front-loaded and every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description compensates by enumerating all status values and describing what an active status returns. Auth usage and secret handling are covered, so an agent has everything needed to call and act on the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: claim_token is single-use and its first consumption yields the api_key. session_id semantics are left to the schema, which already documents it as coming from the provisioning tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Checks') plus the resource ('an account created with provision_account_and_get_payment_link') and enumerates the possible return states (pending_payment, active, expired, suspended). It ties itself directly to the sibling tool that creates the resource, so it is distinguishable from verify_email, search_leads, and the provisioning tool without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete operational guidance: poll every 15-30 seconds while pending_payment, and make the claim call once active. It does not explicitly state when to use this versus any alternative or what to do on 'expired'/'suspended', so it falls just short of full when/when-not coverage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

provision_account_and_get_payment_linkSet up Cold Leads for the human ownerA

Use only when no working Cold Leads API key is available (other Cold Leads tools return missing_api_key or bad_api_key) and the human wants to use Cold Leads. Creates a pending Cold Leads account for the human owner's e-mail and returns a Stripe payment link for the Business plan with API access (price in plan.price, billed monthly until cancelled). Show checkout_url to the human and let them decide; never open, pay or share the link yourself. Keep claim_token secret, then call check_provisioning_status until status is active to receive the API key once.

ParametersJSON Schema

Name	Required	Description
`agent_id`	No	Name of your agent or product; shown to the human on the payment page.
`owner_email`	Yes	E-mail address of the human who will own and pay for the Cold Leads account.
`callback_url`	No	Optional https URL that receives a signed POST when the owner has paid (no secrets in the payload).

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), and the description adds substantial non-derivable detail: the account is created in a pending state, billing is monthly until cancelled, checkout_url must not be opened or paid by the agent, and claim_token must be kept secret. This is exactly the extra context annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The critical usage condition is front-loaded in the first clause, and every sentence is directive rather than filler. It is dense and somewhat long, and it mixes input instructions with output-handling rules, but nothing is redundant with the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return-value burden and does so: it names checkout_url, claim_token, and plan.price, and describes the full async flow through check_provisioning_status to the eventual API key. An agent has everything needed to invoke and follow through correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and all three parameters (agent_id, owner_email, callback_url) are documented in the schema itself. The description references plan.price, checkout_url, and claim_token, but these are outputs rather than inputs, so it adds no input semantics beyond the schema — the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb chain and resource: 'Creates a pending Cold Leads account for the human owner's e-mail and returns a Stripe payment link.' It is clearly distinct from the siblings (verify_email, search_leads, check_provisioning_status), which are named or implied by function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit precondition for use: 'Use only when no working Cold Leads API key is available (other Cold Leads tools return missing_api_key or bad_api_key).' It also states what to do afterward — 'call check_provisioning_status until status is active' — so the agent knows both entry and exit conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_leadsSearch leads by company domainA

Read-onlyIdempotent

Search the leads already in your Cold Leads CRM for a target company domain: contact e-mail, name, company, phone, stage, tags, verification status and a do_not_contact flag. Covers only contacts in your own workspace (Cold Leads has no third-party lead database). Free, uses no credits.

ParametersJSON Schema

Name	Required	Description
`role`	No	Optional keyword such as sales, ceo or marketing, matched against the contact's name, e-mail local part, tags, notes and type.
`limit`	No	Maximum number of leads to return (1–50, default 10).
`domain`	Yes	Company domain, e.g. acme.com. A URL or an e-mail address is reduced to its domain.

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds context not in the annotations: no credit consumption and the workspace-only data boundary that explains why results may be empty.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two dense sentences with zero filler. The core action and search key come first, followed by the scope and cost caveats that matter for interpreting results.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and fully covered input params, the description compensates by listing the returned fields (e-mail, name, company, phone, stage, tags, verification status, do_not_contact). Scope, cost and safety are all accounted for, leaving nothing an agent needs before calling it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the schema fully documents domain, role and limit with formats, ranges and defaults, so the baseline is 3. The description restates the domain input but adds no syntax or matching semantics beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Search the leads already in your Cold Leads CRM') plus the search key ('target company domain'), and enumerates the fields returned. The sibling tools (verify_email, provisioning tools) are functionally unrelated, so there is no realistic confusion to disambiguate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly bounds the tool's scope: 'Covers only contacts in your own workspace (Cold Leads has no third-party lead database)', which functions as a when-not-to-expect-results rule, and notes 'Free, uses no credits'. It stops short of naming an alternative tool for third-party lookup or email verification.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

verify_emailVerify an e-mail addressA

Read-onlyIdempotent

Verifies an e-mail address: syntax, disposable domain, role account and MX records, plus an SMTP mailbox and catch-all check when Cold Leads can open an SMTP connection to the recipient's mail server (otherwise reasons contains smtp_unreachable and catch_all is null). Returns validity (valid, risky or invalid), a score and reason codes. Answers within about 5 seconds; costs 1 credit.

ParametersJSON Schema

Name	Required	Description	Default
`email`	Yes	The e-mail address to verify, e.g. anna@acme.com.

TDQS

A4.3/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations cover safety (readOnly, idempotent, non-destructive, openWorld), and the description adds genuinely new behavioral context: a ~5 second latency, a 1-credit cost, and the degraded-mode contract where SMTP cannot connect (reason smtp_unreachable, catch_all null). This is exactly the kind of operational detail annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One dense paragraph with the core action front-loaded, followed by the fallback behavior, the return shape, and the cost/latency terms. No sentence is filler; each adds a distinct fact an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description steps in to name the returned fields (validity, score, reason codes) and their possible values, and it documents the runtime and billing side effects. Everything needed to call and interpret the result is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and there is a single parameter with its own example and length bounds, so the schema does the heavy lifting. The description adds no formatting or syntax nuance beyond what the schema already documents, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (verifies) and resource (an e-mail address) and enumerates the exact checks performed: syntax, disposable domain, role account, MX records, plus SMTP mailbox and catch-all. An agent can distinguish this from the provisioning/search siblings purely from the description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The context for using it is implied by the tool's narrow subject (verifying a single address) and the sibling names are clearly unrelated, but the description never states when to reach for this tool versus an alternative, nor any preconditions beyond the implicit requirement of an address.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

4 tool updatesv1.0.0Sep 30, 2026
- First observedcheck_provisioning_status
- First observedprovision_account_and_get_payment_link
- First observedsearch_leads
- First observedverify_email

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored 2026-09-30 16:55 across 4 tools

Disambiguation5/5

The four tools cover clearly separate actions: email verification, CRM lead search, account/payment provisioning, and provisioning status check. No two tools overlap in function, so an agent can easily select the right one.

Naming Consistency5/5

All names use snake_case and follow a verb-first pattern (verify_email, search_leads, provision_account_and_get_payment_link, check_provisioning_status). The long provisioning name is descriptive but still consistent with the convention.

Tool Count5/5

Four tools is within the typical 3–15 range and each tool serves a distinct, necessary role in the verification, search, and onboarding workflow. The count is well-scoped for the server's apparent purpose.

Completeness2/5

The server only exposes search and verification for existing leads, with no tools to create, update, delete, or list leads (or to fetch a lead by ID). Core CRM lifecycle operations are missing, which will block agents needing to manage leads.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

email-finderOAuth
com.superagnt
Email finder + verifier for AI agents: find work emails by name and company, check deliverability.
Email Search
1
Fiber AI A
ai.fiber
Search companies, enrich contacts, and reveal emails and phones from your AI agent.
Search Customer Data Platforms Marketing
52
Verifly A
email.verifly
Email verification for AI agents — verify, clean & validate emails; self-onboard + crypto pay
Email Cryptocurrency
172
LayrcakeOAuth
dev.layrcake
Unified GTM API for AI agents: find, enrich, verify, intent, sending, campaigns, replies. One key.
CRM Email
1

Related MCP Servers

sabit-mcp
Email Security
ruwadgroup
A
license
Not graded
quality
B
maintenance
Enables AI agents to verify email addresses through a multi-signal probabilistic pipeline, returning confidence scores and honest statuses (safe/risky/invalid/unknown) with evidence.
Updated 3 months ago (2026-06-17 20:15 UTC)
Apache 2.0
Email Verifier MCP Server
Email Marketing
iguha0
F
license
Not graded
quality
B
maintenance
Enables AI agents to verify email addresses in real-time, checking syntax, DNS, MX records, and SMTP handshake, returning verdicts and deliverability scores without sending actual emails.
Updated 13 days ago (2026-09-17 19:44 UTC)
-
neon-b2b-intelligence
Marketing Networking & Infrastructure Web Scraping
Ansarii
A
license
Not graded
quality
C
maintenance
Enables targeted B2B lead discovery, DNS MX deliverability verification, and extraction of web content into clean Markdown for AI agents.
Updated 23 days ago (2026-09-08 01:11 UTC)
MIT
mxprobe
Email Marketing
andrewchmr
A
license
A
quality
A
maintenance
Enables AI agents to verify email addresses and receive a 'send', 'hold', or 'kill' verdict with the reason, while also managing signup and credits programmatically.
Updated 8 days ago (2026-09-23 10:09 UTC)
5
2
MIT