Hyperleap MCP API Reference: Schemas, Examples, and Rate Limits

TL;DR: The Hyperleap MCP server exposes 9 read-only tools over stdio (and optionally HTTP/SSE) that let any MCP-compatible client query your CRM. Auth is a single API key set as an environment variable. All tools are strictly read-only — no write, update, or delete methods exist. This reference documents every tool's parameter schema, response shape, example JSON-RPC call, and common errors.

This document is the machine-facing complement to the plain-English tools reference. Where that article explains what each tool does and when to use it in natural language, this reference covers the schemas, transports, auth flow, pagination conventions, error codes, and versioning policy a developer needs to wire up an integration programmatically. Read this when you are building a custom MCP client, automating CRM workflows in code, or debugging unexpected tool behavior.

Internal links you will want alongside this reference: MCP overview · Setup guide · Current rate limits per plan · Developer hub.

---

Overview and Transports

The Hyperleap MCP server implements the Model Context Protocol specification — an open standard that defines how AI clients discover and invoke typed tools exposed by external servers. Clients that already support MCP natively (Claude Desktop, Cursor, Raycast, Continue.dev) can connect with no custom code. Custom clients can connect using any MCP-compliant SDK.

Supported Transports

stdio is the standard transport and is supported across all plans. When in doubt, use stdio. The examples in this reference use stdio framing.

Protocol Version

The server targets MCP 1.x. The server advertises its supported protocol version during the initialize handshake. Clients should negotiate downward if needed — the Hyperleap server does not break backwards compatibility within a major protocol version.

What the Server Can and Cannot Do

All 9 tools are read-only. The MCP server can observe your Hyperleap CRM — leads, conversations, activities, notes, pipeline stages, and aggregate metrics — but it cannot create, update, or delete any record. This is a deliberate architectural constraint, not a limitation to be worked around.

---

Authentication

Obtaining an API Key

1. Log into Hyperleap Studio.
2. Navigate to Settings → API Keys.
3. Click Create new key. Give it a descriptive name (e.g., cursor-dev, ci-pipeline-reader).
4. Copy the key immediately — it is displayed once.

API keys are workspace-scoped: a key grants read access to the leads, conversations, and pipeline data within the workspace it was created in. If your organization has multiple workspaces, create a separate key per workspace.

Configuring the MCP Server

Set the key as the HYPERLEAP_API_KEY environment variable before launching the server process. For Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "hyperleap": {
      "command": "npx",
      "args": ["-y", "@hyperleap-ai/mcp-server"],
      "env": {
        "HYPERLEAP_API_KEY": "hlai_live_..."
      }
    }
  }
}

For Cursor (~/.cursor/mcp.json), the structure is identical — see Connect Hyperleap MCP to Cursor for the exact snippet.

Key Rotation

• Rotate keys at least quarterly in production environments.
• Create the replacement key first, update all consumers, then revoke the old key — this prevents a gap in access.
• Keys can be revoked instantly from Settings → API Keys → Revoke.

Security Best Practices

• Never commit the key to source control. Use .env files (git-ignored), CI/CD secret stores, or system keychain integrations.
• One key per environment. Use separate keys for development, staging, and production so you can revoke one without affecting the others.
• Audit key usage from Settings → API Keys — last-used timestamps are shown per key.
• Keys carry no expiry by default. Set a calendar reminder if you prefer time-bounded keys; revoke and recreate on schedule.

---

Tool Reference

All tools use JSON-RPC 2.0 framing over the MCP transport layer. The method is always tools/call. The tool name goes in params.name and tool arguments go in params.arguments. Responses follow the MCP CallToolResult shape: a content array of typed content blocks (almost always text/json).

The schemas below use TypeScript-style type annotations for readability. Optional fields are marked with ?. Fields inferred from observed behavior (rather than published schema docs) are annotated with // inferred.

---

list_leads

Returns a paginated list of leads from your workspace CRM. This is the primary tool for pipeline scans, segment exports, and finding leads that match a filter combination. When called with no arguments it returns the most recent leads up to the server's default page size. Apply filters to narrow results.

Parameters

Returns

{
  "leads": [
    {
      "lead_id": "lead_01H8XKPQR2M3N4T5V6W7Y8Z9A",
      "name": "Jordan Reeves",
      "email": "jordan@acmecorp.com",
      "phone": "+1-555-0100",        // inferred — may be null if not collected
      "status": "contacted",
      "stage_id": "stage_03",
      "channel": "website",
      "tags": ["enterprise", "demo-requested"],
      "created_at": "2026-04-28T14:32:07Z",
      "updated_at": "2026-04-29T09:11:44Z"
    }
  ],
  "total": 247,                       // inferred — total matching count
  "next_cursor": "eyJsaW1pdCI6MjAs...", // null when no more pages
  "has_more": true
}

Example Call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_leads",
    "arguments": {
      "status": "new",
      "channel": "whatsapp",
      "created_after": "2026-05-01T00:00:00Z",
      "limit": 25
    }
  }
}

Example Response (truncated to one lead)

{
  "leads": [
    {
      "lead_id": "lead_01H9AZBCDE2F3G4H5J6K7L8M",
      "name": "Alex Torres",
      "email": "alex@riversidefurnishings.com",
      "phone": null,
      "status": "new",
      "stage_id": "stage_01",
      "channel": "whatsapp",
      "tags": [],
      "created_at": "2026-05-02T08:17:33Z",
      "updated_at": "2026-05-02T08:17:33Z"
    }
  ],
  "total": 14,
  "next_cursor": null,
  "has_more": false
}

Errors

---

get_lead_details

Returns the full profile of a single lead by ID. This is the authoritative source for a lead's contact information, custom fields, assigned stage, tags, and timestamps. Use it after list_leads to hydrate a specific record, or when you already have a lead_id from a webhook or downstream system.

Parameters

Returns

{
  "lead_id": "lead_01H8XKPQR2M3N4T5V6W7Y8Z9A",
  "name": "Jordan Reeves",
  "email": "jordan@acmecorp.com",
  "phone": "+1-555-0100",
  "company": "Acme Corp",             // inferred — present when collected by chatbot
  "status": "qualified",
  "stage_id": "stage_04",
  "stage_name": "Demo Scheduled",    // inferred
  "channel": "website",
  "tags": ["enterprise", "demo-requested"],
  "custom_fields": {                  // inferred — shape varies by workspace configuration
    "budget_range": "$10k–$25k",
    "use_case": "customer support automation"
  },
  "assigned_to": "sam@acmecorp-team.com", // inferred — null if unassigned
  "conversation_count": 3,
  "last_contacted_at": "2026-04-30T11:05:00Z",
  "created_at": "2026-04-28T14:32:07Z",
  "updated_at": "2026-04-30T11:05:00Z"
}

Example Call

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_lead_details",
    "arguments": {
      "lead_id": "lead_01H8XKPQR2M3N4T5V6W7Y8Z9A"
    }
  }
}

Example Response

{
  "lead_id": "lead_01H8XKPQR2M3N4T5V6W7Y8Z9A",
  "name": "Jordan Reeves",
  "email": "jordan@acmecorp.com",
  "phone": null,
  "company": "Acme Corp",
  "status": "qualified",
  "stage_id": "stage_04",
  "stage_name": "Demo Scheduled",
  "channel": "website",
  "tags": ["enterprise", "demo-requested"],
  "custom_fields": {},
  "assigned_to": null,
  "conversation_count": 2,
  "last_contacted_at": "2026-04-29T16:44:11Z",
  "created_at": "2026-04-28T14:32:07Z",
  "updated_at": "2026-04-29T16:44:11Z"
}

Errors

---

get_lead_conversations

Returns all chatbot conversations associated with a lead, ordered by most recent first. Each item in the list is a conversation summary — to get the full message-by-message transcript, pass the conversation_id to get_conversation. Use this tool to understand how many times a lead has engaged and which sessions were the most substantive.

Parameters

Returns

{
  "conversations": [
    {
      "conversation_id": "conv_01J1ABCDE2F3G4H5J6K7L8M9N",
      "lead_id": "lead_01H8XKPQR2M3N4T5V6W7Y8Z9A",
      "channel": "website",
      "started_at": "2026-04-29T10:00:00Z",
      "ended_at": "2026-04-29T10:08:43Z",  // inferred — null if ongoing
      "message_count": 12,
      "status": "completed"                  // inferred: completed | active | abandoned
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Example Call

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_lead_conversations",
    "arguments": {
      "lead_id": "lead_01H8XKPQR2M3N4T5V6W7Y8Z9A",
      "limit": 10
    }
  }
}

Example Response

{
  "conversations": [
    {
      "conversation_id": "conv_01J1ABCDE2F3G4H5J6K7L8M9N",
      "lead_id": "lead_01H8XKPQR2M3N4T5V6W7Y8Z9A",
      "channel": "website",
      "started_at": "2026-04-29T10:00:00Z",
      "ended_at": "2026-04-29T10:08:43Z",
      "message_count": 12,
      "status": "completed"
    },
    {
      "conversation_id": "conv_01J2PQRST3U4V5W6X7Y8Z9A0B",
      "lead_id": "lead_01H8XKPQR2M3N4T5V6W7Y8Z9A",
      "channel": "whatsapp",
      "started_at": "2026-04-28T14:32:10Z",
      "ended_at": "2026-04-28T14:39:55Z",
      "message_count": 7,
      "status": "completed"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Errors

---

get_conversation

Returns the full message-by-message transcript of a single conversation by conversation_id. Each message in the messages array includes the sender role (user or assistant), the message text, and a timestamp. This is the tool to use when you need to read exactly what a lead said — for coaching, compliance review, or building downstream summaries.

Parameters

Returns

{
  "conversation_id": "conv_01J1ABCDE2F3G4H5J6K7L8M9N",
  "lead_id": "lead_01H8XKPQR2M3N4T5V6W7Y8Z9A",
  "channel": "website",
  "started_at": "2026-04-29T10:00:00Z",
  "ended_at": "2026-04-29T10:08:43Z",
  "messages": [
    {
      "role": "assistant",
      "content": "Hi there! How can I help you today?",
      "timestamp": "2026-04-29T10:00:02Z"
    },
    {
      "role": "user",
      "content": "I'm looking for something to handle support tickets automatically.",
      "timestamp": "2026-04-29T10:00:18Z"
    },
    {
      "role": "assistant",
      "content": "Great — we can definitely help with that. Are you handling support across website chat, WhatsApp, or both?",
      "timestamp": "2026-04-29T10:00:19Z"
    }
  ]
}

Example Call

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "get_conversation",
    "arguments": {
      "conversation_id": "conv_01J1ABCDE2F3G4H5J6K7L8M9N"
    }
  }
}

Errors

---

get_lead_activities

Returns a chronological activity timeline for a lead. Activities include inbound messages, outbound replies, stage changes, tag assignments, and any system events recorded against the lead. Use this tool when you need a complete audit trail — not just conversations, but all CRM-level events.

Parameters

Returns

{
  "activities": [
    {
      "activity_id": "act_01K1ABCDE2F3G4H5J6K7L8M9N", // inferred
      "lead_id": "lead_01H8XKPQR2M3N4T5V6W7Y8Z9A",
      "type": "stage_change",     // inferred: message | stage_change | tag | note | reply
      "description": "Stage changed from 'New' to 'Contacted'",
      "performed_by": "system",   // inferred: system | user email
      "timestamp": "2026-04-28T15:01:22Z"
    },
    {
      "activity_id": "act_01K2PQRST3U4V5W6X7Y8Z9A0B",
      "lead_id": "lead_01H8XKPQR2M3N4T5V6W7Y8Z9A",
      "type": "message",
      "description": "Lead sent a message via WhatsApp",
      "performed_by": "system",
      "timestamp": "2026-04-28T14:32:10Z"
    }
  ],
  "next_cursor": "eyJsaW1pdCI6MjAs...",
  "has_more": true
}

Example Call

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "get_lead_activities",
    "arguments": {
      "lead_id": "lead_01H8XKPQR2M3N4T5V6W7Y8Z9A",
      "limit": 20
    }
  }
}

Errors

---

get_lead_notes

Returns the internal notes that team members have added to a lead record. Notes are not visible to the lead — they are your team's working memory about the account. This tool is useful for briefing an AI before a sales call, auditing what a rep has documented, or consolidating context before escalation.

Parameters

Returns

{
  "notes": [
    {
      "note_id": "note_01L1ABCDE2F3G4H5J6K7L8M9N", // inferred
      "lead_id": "lead_01H8XKPQR2M3N4T5V6W7Y8Z9A",
      "content": "Called Jordan — confirmed they're evaluating three vendors. Decision by end of Q2. Primary concern is WhatsApp channel parity.",
      "author": "sam@example-team.com",
      "created_at": "2026-04-30T11:06:00Z",
      "updated_at": "2026-04-30T11:06:00Z"
    }
  ]
}

Example Call

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "get_lead_notes",
    "arguments": {
      "lead_id": "lead_01H8XKPQR2M3N4T5V6W7Y8Z9A"
    }
  }
}

Errors

---

get_pipeline_stages

Returns the pipeline stage definitions configured in your workspace, along with the current lead count in each stage. Use this tool to enumerate valid stage_id values for list_leads, or to get a quick snapshot of how leads are distributed across your funnel without querying individual records.

Parameters

This tool takes no parameters.

Returns

{
  "stages": [
    {
      "stage_id": "stage_01",
      "name": "New Lead",
      "position": 1,            // inferred — sort order in the pipeline view
      "lead_count": 83
    },
    {
      "stage_id": "stage_02",
      "name": "Contacted",
      "position": 2,
      "lead_count": 41
    },
    {
      "stage_id": "stage_03",
      "name": "Qualified",
      "position": 3,
      "lead_count": 19
    },
    {
      "stage_id": "stage_04",
      "name": "Demo Scheduled",
      "position": 4,
      "lead_count": 7
    },
    {
      "stage_id": "stage_05",
      "name": "Closed Won",
      "position": 5,
      "lead_count": 22
    }
  ]
}

Example Call

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "get_pipeline_stages",
    "arguments": {}
  }
}

Errors

---

get_crm_dashboard

Returns aggregate CRM metrics for the workspace, optionally scoped to a date range. Metrics include lead volume, channel breakdown, conversion rates, and stage distribution. This is the tool to use for weekly summaries, executive reporting, and trend detection — when you need numbers across the whole pipeline rather than data on individual leads.

Parameters

Returns

{
  "period": {
    "start_date": "2026-04-01",
    "end_date": "2026-04-30"
  },
  "summary": {
    "total_leads": 312,
    "new_leads": 84,
    "converted_leads": 29,
    "lost_leads": 11,
    "conversion_rate": 0.093          // inferred — converted / total as decimal
  },
  "by_channel": {
    "website": 188,
    "whatsapp": 96,
    "instagram": 18,
    "facebook": 10
  },
  "by_stage": {                        // inferred — mirrors get_pipeline_stages counts
    "stage_01": 83,
    "stage_02": 41,
    "stage_03": 19,
    "stage_04": 7,
    "stage_05": 22
  },
  "avg_response_time_seconds": 4.2    // inferred — average bot first-response latency
}

Example Call

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "get_crm_dashboard",
    "arguments": {
      "start_date": "2026-05-01",
      "end_date": "2026-05-07"
    }
  }
}

Errors

---

extract_lead_insights

Runs an LLM-powered extraction pass over a lead's conversation history and returns structured insights: inferred buying intent, identified objections, conversation sentiment, and a suggested next action. Unlike the other 8 tools — which return stored CRM data — this tool performs real-time inference. Response latency is higher (typically 2–5 seconds). Each call consumes AI credits from your Hyperleap plan.

Parameters

Returns

{
  "lead_id": "lead_01H8XKPQR2M3N4T5V6W7Y8Z9A",
  "insights": {
    "buying_intent": "high",           // inferred: high | medium | low | unknown
    "objections": [
      "Concerned about WhatsApp channel feature parity",
      "Wants to see integration with their existing CRM before deciding"
    ],
    "sentiment": "positive",           // inferred: positive | neutral | negative | mixed
    "key_topics": [
      "customer support automation",
      "WhatsApp",
      "CRM integration",
      "Q2 evaluation timeline"
    ],
    "suggested_next_action": "Send a WhatsApp-specific feature walkthrough and offer a technical demo with their CRM team.",
    "confidence": 0.87                 // inferred — model confidence in the extraction
  },
  "generated_at": "2026-05-19T09:33:11Z"
}

Example Call

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "extract_lead_insights",
    "arguments": {
      "lead_id": "lead_01H8XKPQR2M3N4T5V6W7Y8Z9A"
    }
  }
}

Errors

---

Pagination Patterns

Three tools support cursor-based pagination: list_leads, get_lead_conversations, and get_lead_activities. The pattern is identical across all three.

How Cursor Pagination Works

On the first call, omit the cursor argument. The response contains a next_cursor field (an opaque base64-encoded string) and a has_more boolean:

{
  "leads": [...],
  "next_cursor": "eyJsaW1pdCI6MjAsIm9mZnNldCI6MjB9",
  "has_more": true
}

To fetch the next page, pass the value of next_cursor as the cursor argument on your next call — along with the same filter arguments you used on the first call. Do not attempt to construct or decode the cursor — it is opaque by design and its encoding may change without notice.

When has_more is false (or next_cursor is null), you have reached the last page. Stop iteration.

Reference Implementation (TypeScript)

async function fetchAllLeads(
  callTool: (name: string, args: Record<string, unknown>) => Promise<unknown>,
  filters: Record<string, unknown> = {}
) {
  const results: unknown[] = [];
  let cursor: string | undefined;

  do {
    const args = cursor ? { ...filters, cursor } : filters;
    const page = await callTool("list_leads", args) as {
      leads: unknown[];
      next_cursor: string | null;
      has_more: boolean;
    };

    results.push(...page.leads);
    cursor = page.next_cursor ?? undefined;
  } while (cursor);

  return results;
}

The same pattern applies to get_lead_conversations and get_lead_activities — substitute the tool name and the array field name (conversations, activities).

Cursor Stability

Cursors are point-in-time snapshots. If new leads are created between paginated calls, those records may not appear in the current paginated session. This is the expected behavior for read-heavy workloads. For real-time new-lead detection, use Hyperleap webhooks rather than polling list_leads.

---

Rate Limits and Quotas

Rate limits for the Hyperleap MCP server are tied to your Hyperleap subscription plan. The exact request-per-minute and daily call limits differ by plan and are subject to change as plans evolve.

Do not hardcode rate limit numbers in your integration. Instead, consult /help/integrations/crm-mcp/tools for current limits per plan. That page is kept up to date when plan limits change.

How Limits Are Counted

Each MCP tool call counts as one request against your quota. extract_lead_insights additionally consumes AI credits from your plan's response balance, because it runs a live inference pass. Pagination calls (passing a cursor) count as separate requests.

Handling 429 Responses

When your client receives a 429 Too Many Requests error, apply exponential backoff with jitter:

async function callWithRetry(
  fn: () => Promise<unknown>,
  maxAttempts = 5
): Promise<unknown> {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err: unknown) {
      const isRateLimited =
        typeof err === "object" && err !== null && "code" in err && (err as { code: number }).code === 429;
      if (!isRateLimited || attempt === maxAttempts - 1) throw err;

      const baseDelay = Math.pow(2, attempt) * 1000;         // 1s, 2s, 4s, 8s...
      const jitter = Math.random() * baseDelay * 0.25;
      await new Promise((r) => setTimeout(r, baseDelay + jitter));
    }
  }
}

Check whether the 429 response includes a Retry-After header — if present, use that value as the minimum delay rather than the backoff formula.

extract_lead_insights and Credit Consumption

Because extract_lead_insights consumes AI credits, aggressive polling of this tool can deplete your plan's monthly balance faster than expected. Recommended pattern: call extract_lead_insights on a lead once, cache the result with a TTL of several hours, and re-run only when new conversation activity has occurred. Compare get_lead_activities to detect new activity before deciding whether to re-extract.

---

Error Codes

This section documents the HTTP-level and MCP-level errors you can receive across any tool call.

MCP Transport-Level Errors

If the MCP server process fails to start (not an API error — the stdio process itself crashes), check:

• HYPERLEAP_API_KEY is set in the env block of your MCP server config, not in your shell's general environment (the spawned process may not inherit it).
• The npx package version you are running is current. Update with npx -y @hyperleap-ai/mcp-server@latest to verify the latest version resolves correctly.
• Your network can reach api.hyperleapai.com — the stdio process makes outbound HTTPS calls.

---

Versioning Policy

The Hyperleap MCP server uses semantic versioning for the npm package (@hyperleap-ai/mcp-server).

Backwards-compatible additions (new optional parameters, new response fields, new tools) are safe to absorb without code changes. Breaking changes require a deliberate upgrade.

Pinning in Production

Pin the MCP server package to a specific minor version in production. Using latest in production means a major-version bump can break your integration without warning.

Claude Desktop config — pin example:

{
  "mcpServers": {
    "hyperleap": {
      "command": "npx",
      "args": ["-y", "@hyperleap-ai/mcp-server@1.0"],
      "env": {
        "HYPERLEAP_API_KEY": "hlai_live_..."
      }
    }
  }
}

Subscribe to the Hyperleap developer changelog or watch the npm package for release notifications.

---

Changelog

v1.0.0 — May 2026

Initial public release of the Hyperleap MCP server.

• 9 read-only tools: list_leads, get_lead_details, get_lead_conversations, get_conversation, get_lead_activities, get_lead_notes, get_pipeline_stages, get_crm_dashboard, extract_lead_insights.
• stdio transport supported on all plans.
• Cursor-based pagination on list_leads, get_lead_conversations, get_lead_activities.
• API key authentication via HYPERLEAP_API_KEY environment variable.

---

Frequently Asked Questions

What version of the Model Context Protocol does the Hyperleap MCP server implement?

The server targets MCP 1.x. During the initialize handshake, the server advertises its supported protocol version and negotiates with the client. For the canonical MCP specification, see spec.modelcontextprotocol.io. The MCP project's main site (modelcontextprotocol.io) has SDK documentation for building custom clients in Python, TypeScript, and other languages.

Can I use the MCP server with a custom client that is not Claude Desktop or Cursor?

Yes. Any client that implements the MCP specification can connect to the Hyperleap server. The only requirement is support for the stdio transport (standard) or HTTP/SSE transport (where available). SDKs exist for TypeScript, Python, Java, and Kotlin — see modelcontextprotocol.io for the current SDK list.

Why are all 9 tools read-only? Will write tools be added?

Read-only is a deliberate architectural constraint, not a roadmap gap. The MCP server is designed for observation and analysis workflows — briefing an AI before a call, generating pipeline reports, debugging chatbot transcripts. Write operations (creating leads, updating stages, logging notes) remain in Hyperleap Studio and the REST API. This boundary keeps the MCP integration safe to use in exploratory AI sessions without risk of unintended data modification.

How does the API key differ from the REST API key?

The same API key infrastructure serves both the MCP server and the Hyperleap REST API. A key created in Hyperleap Studio → Settings → API Keys can be used for either integration. The key is workspace-scoped in both cases. You can choose to use the same key or create separate keys per integration for easier auditing and revocation.

What happens if my API key is revoked while an MCP session is active?

In-flight tool calls will return 401 Unauthorized. Subsequent calls in the same session will also return 401. The MCP session itself may not terminate immediately (the stdio process stays alive), but all tool calls will fail until the server process is restarted with a valid key.

Does extract_lead_insights always consume credits, even if the response is cached?

Each call to extract_lead_insights triggers a live inference run and consumes credits — there is no server-side caching between calls. Client-side caching is your responsibility. The recommended pattern is to store the response with a TTL and compare the lead's latest updated_at or activity count before deciding whether to re-call the tool.

What is the difference between get_lead_conversations and get_conversation?

get_lead_conversations returns a list of conversation summaries for a lead — useful for seeing how many sessions a lead has had and when they occurred, without loading the full message transcript for each. get_conversation returns the full message-by-message transcript of a single conversation. A typical pattern is to call get_lead_conversations first to find the most relevant session, then call get_conversation with that ID to read the actual exchange.

Can I filter get_lead_activities by activity type?

The current v1.0.0 tool does not accept a type filter — it returns all activity types for a lead in chronological order. If you need only stage changes or only messages, filter the returned array client-side. Check /help/integrations/crm-mcp/tools for any new parameters added after the v1.0.0 release.

What should I do if I get a 500 error that persists across retries?

A single 500 is worth one immediate retry after a brief wait (2–5 seconds). If the error recurs across multiple retries, capture the full error response body — it typically includes a request ID. Contact Hyperleap support at /help with the request ID, the tool name, and the arguments you passed (redacting any PII if appropriate). Do not include your raw API key in support requests.

Where do I find the current rate limit values for my plan?

Rate limit numbers are published at /help/integrations/crm-mcp/tools and kept current as plan limits evolve. They are not documented in this reference because they vary by plan and can change. Subscribe to the developer changelog at /developers to receive notifications when limits change.

---

Related Articles

Engineering

Build a Sales Agent with Hyperleap MCP (Read-Only, Scheduled, Safe)

A hands-on guide to building a non-interactive sales agent on top of Hyperleap's read-only MCP server — the agent loop, the tools it uses, example prompts, and how to schedule or trigger it.

May 27, 202615 min read

Engineering

Multi-MCP Workflows: Hyperleap + HubSpot + Linear in Claude

How to combine multiple MCP servers — Hyperleap, HubSpot, Linear — into a single Claude workflow that turns chatbot leads into enriched CRM records and follow-up tickets.

May 17, 202618 min read

Engineering

Connect Hyperleap MCP to Cursor for Developer Workflows

Step-by-step setup for using Hyperleap's MCP server inside Cursor. Pull live lead data, prototype agents, and debug integrations from your IDE.

May 14, 202616 min read

Engineering

The 9 Hyperleap MCP Tools, Explained with Real Prompts

Reference guide to every tool in Hyperleap's MCP server. Parameters, example prompts, sample responses, and when to use each of the 9 read-only methods.

May 6, 202629 min read

View all articles