Warmly's MCP server and REST API are live at opps-api.getwarmly.com. OAuth-based MCP access from Claude Desktop, Claude Code, Cursor, and any MCP-compatible agent — plus REST endpoints with API key auth for everything else. Three read-only tools.

Installation Instructions

Claude Desktop

1. Open Customize → Connectors

2. Click the + next to Connectors, then Add custom connector

3. 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)

4. Click Add. A browser tab opens for OAuth. Sign in with your Warmly account

5. Tools become available in chats automatically

   

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=3d5c193a-bb60-4833-8301-896cdd3ef88a

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: 3d5c193a-bb60-4833-8301-896cdd3ef88a"

Where to find your orgId. Inside Warmly, open Settings → General — your organization ID is shown there. If you can't find it, email [email protected] and we'll send it over.

The Three Tools Available

1. 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.

2. 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.

3. 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.

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.

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.