Coldleads MCP Server

Cold Leads MCP server

Model Context Protocol server for Cold Leads, the B2B outreach CRM. It exposes the hosted workspace tools to local MCP clients (Claude Desktop, Claude Code, Cursor, Windsurf, VS Code): contacts, imports, synced conversations, templates, campaigns, website capture, lead search, and verification. Without an API key, it can also ask the human owner to approve a subscription.

npx -y @coldleads/mcp-server

Try it without a key

The hosted demo server has the same tools over a sample workspace (fictional contacts on .example domains). It never sends e-mail and uses no credits:

claude mcp add --transport http coldleads-demo https://coldleads.app/api/mcp/demo

Then ask: "Verify these three contacts and prepare outreach drafts. Don't send anything until I approve. Jana Dvořák jana.dvorak@ridgeline.example, info@harborlane.example, Piotr Kowalski piotr@quillmetrics.example". Any client that supports remote (Streamable HTTP) MCP servers can use the same URL. A complete agent built on it: cold-leads-ai-sales-agent.

Demo limits:

Tools

Responses are compact JSON in a text block. An illustrative result for an address whose mailbox could not be checked (example.com is reserved for documentation):

{"status":"success","email":"jane.doe@example.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}.

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", "@coldleads/mcp-server"],
      "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 @coldleads/mcp-server

VS Code

.vscode/mcp.json:

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

Hosted endpoint (no install)

Clients that support remote servers can connect directly with a secret key:

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

The stdio server discovers workspace tools from https://coldleads.app/api/mcp and forwards their calls to the hosted MCP service, so the hosted and local tools use the same account, policy and sending safeguards. It also includes keyless onboarding tools. ChatGPT connects to the hosted endpoint with OAuth 2.1; enable Developer mode in ChatGPT, add the endpoint, sign in to Cold Leads and review the requested access. Other remote MCP clients can use the API-key header shown above.

Docker

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

Configuration

Agent onboarding without a key

1. The agent calls provision_account_and_get_payment_link with the owner's e-mail.
2. 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.
3. The agent polls check_provisioning_status with session_id and claim_token every 15–30 seconds.
4. 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.
5. 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

MIT © 2026 Anton Tkachenko