TL;DR. Warmly's MCP server is live at https://opps-api.getwarmly.com/api/mcp. Install in Claude Code with one line:
claude mcp add --transport http warmly https://opps-api.getwarmly.com/api/mcp
OAuth login on first call. No API key to manage. Three read-only tools. Free with every Warmly account, 250 credits a month. Prefer REST? The same tools are exposed at /api/agent-tools/execute with API key auth — see REST API below.
Warmly's MCP in action. ~3 minutes.The Shift
Six months ago, Warmly lived inside Warmly. You logged in to see who was on your site. You set up Slack alerts. You exported lists. The data was great. It lived behind a UI.
That's the wrong place for it now. The teams I respect most aren't logging into ten dashboards anymore. They're talking to their stack. They tell Claude "show me everyone on the pricing page today who matches our ICP, write the first-touch email, push it to my HubSpot sequence." The agent does it.
So we shipped the plumbing. Warmly's MCP server is live. The External API is live. Both surface the same data your dashboard does: identified visitors and the companies they came from. From any agent. In one call.
Install in 30 Seconds
Claude Desktop
- Open Customize → Connectors
- Click the + next to Connectors, then Add custom connector
- Name:
Warmly. URL: https://opps-api.getwarmly.com/api/mcp (if your account is in multiple Warmly workspaces, you'll need an orgId — see Specify your organization below) - Click Add. A browser tab opens for OAuth. Sign in with your Warmly account
- Tools become available in chats automatically
The Add custom connector dialog in Claude Desktop. Name your connector Warmly and paste the MCP endpoint URL.Claude Code, Cursor, Zed
Install in one line:
claude mcp add --transport http warmly https://opps-api.getwarmly.com/api/mcp
(Multi-org users add --scope user plus a header — see Specify your organization.)
First tool call opens a browser for OAuth. After login, /mcp lists the tools. To remove later: claude mcp remove warmly.
Specify your organization
If your Warmly account belongs to more than one organization, you'll need to tell the MCP which one to use — otherwise you'll see a 401 missing_org_context. This also applies if you're an admin pinning a connector to a specific workspace (common for agencies managing multiple clients). Two ways to do it.
Query string — cleanest for Claude Desktop. Append ?organization_id=<your-org-id> to the MCP URL:
https://opps-api.getwarmly.com/api/mcp?organization_id=00000000-0000-0000-0000-000000000000
Header — cleanest for CLI installs. Pass X-Warmly-Organization-Id on the install command. The --scope user flag makes the connector available across all your projects, not just the current one.
Example:
claude mcp add --scope user --transport http warmly-prod https://opps-api.getwarmly.com/api/mcp --header "X-Warmly-Organization-Id: 00000000-0000-0000-0000-000000000000"
Where to find your orgId. Inside Warmly, open Settings → General — your organization ID is shown there. If you can't find it, email support@warmly.ai and we'll send it over.
The Three Tools
list_warm_visitors
Identified people who visited your site, with full context. Company profile, contact profile, every page they visited, session time, last seen, UTM source, and whether they exist in your HubSpot, Salesforce, or Pipedrive. Free to call.
Inputs: timeWindow (past_day default, past_week max), take (1-500, default 25), offset, requireBusinessContact (LinkedIn handle + work email only), searchTerm (substring against name/email/company), countries (ISO codes), industries, employeeSizeBands (e.g. 11-50, 51-200, 10000+), pagesVisitedContains.
list_warm_accounts
Same data grouped by company. Adds visitor aggregations: total sessions, identified visitors, distinct pages. For when you want the account view instead of the contact view. Free to call.
Inputs: same shape as list_warm_visitors minus the contact-level filters.
get_credits_remaining
Snapshot of your workspace's credit balance for the current monthly window. Lets your agent check before launching a big query and warn you when you're getting close to the limit. Free to call. Takes no inputs.
What You Get Back
Every list_warm_visitors result is a visitor object. Each one includes:
- Visitor basics — lastSeen timestamp, totalSessions, sessionTime, page-visit array with paths and counts, UTM params.
- Company profile — name, domain, industry, sub-industry, employee range, estimated annual revenue, city, state, country, LinkedIn handle.
- Contact profile — fullName, employment_title, employment_seniority, LinkedIn handle, and a bio when available.
- Email and phone — work email is included when identified; phone number reveal is coming soon.
- CRM intersection —
crmProviders array tells you whether the visitor already exists in your HubSpot, Salesforce, or Pipedrive.
That last one is the dedupe story. About half of identified visitors are already known to someone on your team. The MCP tells you which ones are net-new.
REST API
The REST API in 60 seconds.The same three tools are exposed as a REST API for systems that don't speak MCP. Auth is per-org API key, not OAuth. Base URL: https://opps-api.getwarmly.com/api.
Run a tool by POSTing to /agent-tools/execute with Authorization: Bearer $WARMLY_API_KEY and a JSON body containing toolName, organizationId, and input. Example body:
{
"toolName": "list_warm_visitors",
"organizationId": "<your-org-id>",
"input": { "take": 25, "timeWindow": "past_day" }
}
The four endpoints:
POST /agent-tools/execute — Run a tool. Returns inline for sync tools; for async tools, poll executions/:id.GET /agent-tools/executions/:id — Look up one past run by id. Returns input, output, status, timing.GET /agent-tools/executions — List past runs. Filter by toolName, status, externalRef, or date range.GET /agent-tools/tools — List the tools your org has access to, with each tool's input schema.
Two optional fields on execute worth knowing. reasoning is a free-text note describing why you called the tool — stored for audit. externalRef is your own reference id (e.g. a request id from your system) — useful for searching runs later.
A request that hit the API correctly always responds with 202, even when the tool itself failed. To know whether the tool succeeded, check status and output.success in the response body — not the HTTP status. Tool-level failures come back as 202 with a human-readable userFacingError.
API keys are issued per organization from the Warmly admin UI — same place where you find your organizationId. Each key is tied to one org and acts on its behalf. Treat it like a password.
Async tool flow. A few tools (like sequence enrollment) run async. The initial /execute call returns immediately with status: pending or running. Poll GET /agent-tools/executions/:id until status reaches a terminal value: succeeded, failed, cancelled, or awaiting_approval. Synchronous tools skip this and return the result inline.
Tool discovery. Call GET /agent-tools/tools?organizationId=<your-org-id> to see exactly which tools your org can call. The response is an array of { name, description, isAsync, inputSchema }. The inputSchema is JSON Schema — use it to introspect what each tool accepts before you build against it. New tools show up here as we ship them.
Input limits. The input object is capped at 256 KB serialized, 1,000 total keys, 32 levels deep. reasoning is capped at 50,000 characters. Anything bigger comes back as 400.
Postman collection here.
How to create an API key in the Warmly admin. ~90 seconds.How Credits Work
One credit pool per workspace. Resets monthly. Credits are spent the moment a visitor on your site is identified.
What charges: 1 credit when the company is identified, 1 credit when the contact is identified, maximum 2 credits per unique visitor per month.
What doesn't charge: list_warm_visitors reads, list_warm_accounts reads, get_credits_remaining, and the same visitor being identified again within the same calendar month (per-month dedupe).
The dedupe matters more than people expect. Once Jane from Acme is identified on day 5, every subsequent session of hers this month is free. Credits work less like a meter and more like a library card. You're paying for the universe of accounts you've unlocked, not for every read.
When the dedupe window resets. The dedupe ledger and the credit pool refresh together at the start of each calendar month. Whatever you paid for in June is free to re-identify until 11:59 PM on June 30. At midnight on July 1, the credit pool refills and the dedupe ledger clears — anyone who returns to your site on July 1 charges fresh, even if you already paid for them in June. Your in-app credit meter shows the next reset date so you can plan large pulls accordingly.
Rate limits: 60 requests per minute on free tier, 120 per minute on paid. The server returns HTTP 429 when you exceed; back off about 60 seconds and retry.
Troubleshooting
- Browser doesn't open for OAuth — Popup blocker or stale session. Re-run
claude mcp add or re-add the connector in Desktop. 401 unauthorized — MCP token expired or revoked, or REST API key invalid. For MCP: remove and re-add the connector. For REST: regenerate the key in the admin UI.401 missing_org_context — No org could be resolved (admin passed a bad header, or user has multiple memberships and no header). For MCP, pass ?organization_id=<uuid> in the URL or X-Warmly-Organization-Id as a header. For REST, pass organizationId in the body.403 on REST calls — The organizationId you sent doesn't match the API key's org. Use the org the key was issued for, or generate a new key for that org.- Tools missing from
/mcp list — Connector not authenticated yet, or filter rejected an async/write tool. Confirm OAuth completed; the server only exposes read-only sync tools by design. HTTP 429 rate limit — Hit the per-minute call limit (60 free, 120 paid). Back off about 60 seconds and retry; reduce batch size on next call.
Pricing
API/MCP self-serve tiers ladder up by credit volume. All tiers include the same three tools, OAuth-based MCP access, and REST API access via key. Commit to a quarter or a year via sales for a better unit rate.
Tier
Price
Credits/mo
$/credit
Annual
Free
$0
250
—
$0
Starter
$99/mo
500
$0.198
$1,188
Growth Popular
$199/mo
1,000
$0.199
$2,388
Pro
$499/mo
2,500
$0.200
$5,988
Enterprise
2,500+
—
Custom
Need more than 2,500 credits/mo? Talk to sales. Enterprise adds Inbound and Outbound Agents, AI Studio, retargeting, premium identification, multi-CRM bidirectional sync, dedicated AM, and SLA — plus a better unit rate on quarterly or annual commitments.
When You Run Out of Credits
The MCP returns a structured error your agent can relay verbatim. Reads from list_warm_visitors and list_warm_accounts keep working on everyone already identified. Re-pulling anyone you've already paid for this month keeps working. New visitor identifications get paused until either the calendar month resets or you upgrade.
Heads-up: the credit pool is shared across the whole Warmly product. Running out also pauses visitor identifications and orchestrations in the app itself. The MCP isn't on its own meter.
Upgrades are self-serve via HubSpot payment links. Pick your tier, pay, use the same email as your Warmly account. We bump your tier within one business day. Webhook automation lands later this quarter.
Support
For API issues (MCP or REST), email support@warmly.ai. For account, billing, or product questions, talk to sales.
What's Coming Next
- Self-serve upgrade and downgrade inside the Warmly app, with the credit ceiling bumped the moment payment lands.
- Phone number reveals on identified visitors.
- Third-party intent signal lookups via MCP and REST (hiring, news, funding, social) — already live inside the app, agent-side access coming soon.
- Async write tools so your agent can push contacts to HubSpot, Salesforce, or a sequence directly.
- Webhooks on execution status, so async tool callers can skip the polling step.
This is the surface I want Warmly to be in 2026. Not a dashboard you log into. A data layer your agents talk to. Tell me what's broken. alan@warmly.ai.