Leadspace offers a Model Context Protocol (MCP) server that exposes the Leadspace GTM Data Intelligence Cloud to any MCP-compatible AI client — Claude, Cursor, VS Code, n8n, Codex, or a custom LLM pipeline — as a set of tools callable in natural language. This article presents the technical specifications and requirements in order to connect to and operate the Leadspace MCP server.

Tools are discovered at connection time via the standard MCP tool-listing handshake, so a client always sees the current tool set without configuration.

Setup

Access requires a free Leadspace Sidekick account. There is no separate developer signup, API key, or admin provisioning step.

1. Install Leadspace Sidekick from the Chrome Web Store.
2. Register with a work email. Personal email domains are rejected.
3. Use that same login to authenticate the MCP server.

Please note that API-key authentication is not supported. Every client authenticates through the same browser-based OAuth sign-in using your Sidekick login.

Transport

All connections use Streamable HTTP (RFC 9728) over HTTPS. This is native for Claude clients. All other clients connect through the mcp-remote bridge, which runs a local proxy and handles the browser sign-in. Node.js is required for bridge clients.

Endpoint

Base URL is:

https://skprod.leadspace.com/mcp/v1

This is the canonical form, with no trailing slash. The mcp-remote bridge commands in this document append a local proxy port, which is expected.

Authentication

Authentication is OAuth 2.1 with a browser-based sign-in that triggers automatically on first connection. Leave any OAuth Client ID and Client Secret fields blank — client registration is handled server-side.

1. The client's first request returns 401 with a WWW-Authenticate header pointing at the OAuth metadata. This is expected OAuth discovery, not a failure.
2. A browser window opens. Sign in with your Sidekick login (work email and password).
3. An access token (approximately 24 hours) and a refresh token are issued and stored by the client. Refresh is automatic and auto-rotating.
4. The client reports "Connected" and all tools become available.

Re-authentication is required only if the token expires or the client is reinstalled.

OAuth callback ports

Server version

Major 1, minor 0. Query get_mcp_version_info for live values.

Client Setup

Claude Web

Settings > Connectors > Add custom connector > paste the endpoint > leave the OAuth fields blank > Connect > sign in with your Sidekick login.

Claude Desktop

Settings > Connectors > Name: Leadspace, URL: the production endpoint > leave the OAuth fields blank > Add / Connect.

Claude Code

claude mcp add --transport http leadspace https://skprod.leadspace.com/mcp/v1

Then authenticate by running /mcp, selecting leadspace, and choosing Authenticate.

Cursor

npx -y mcp-remote https://skprod.leadspace.com/mcp/v1/ 4902 --transport http-only

Then go to Cursor Settings > MCP > Add, pointing at localhost:4902.

VS Code, n8n, and any other MCP client

npx -y mcp-remote https://skprod.leadspace.com/mcp/v1/ 4903 --transport http-only

Use any port in the range 4903–4910 to avoid collisions.

Codex

codex mcp add leadspace --url https://skprod.leadspace.com/mcp/v1
codex mcp login leadspace

Complete the browser sign-in yourself. Do not pass tokens or client credentials.

Tool Reference

Seven tools are available, all read-only lookups. Cost is per call. In every response, credits_consumed is the total charged and credits_breakdown is the authoritative per-field map. The total always equals the sum of the breakdown.

Reveals are idempotent per (user + contact + field): re-revealing the same field on the same contact by the same user is free. Examples below use public firmographic data and a masked-contact edge case.

enrich_account

Returns a firmographic and account-intelligence profile for a company. Cost: 0 credits.

Parameters

Returns

name, website, industry, sub_industry, sic, naics (with descriptions), employee_range, revenue_range, ownership_type, founded_year, HQ fields, description, linkedin_url, logo_url, ls_id, reference_id, cached, credits_consumed, and corporate_hierarchy (site / domestic_ultimate / global_ultimate).

Sample response

{
  "enrichment_status": "Company Enriched",
  "company": {
    "name": "Salesforce, Inc.",
    "industry": "Information",
    "employee_range": "> 10K",
    "revenue_range": "> $1 Billion",
    "corporate_hierarchy": {
      "site": {...},
      "global_ultimate": {...}
    }
  },
  "reference_id": "...",
  "cached": false,
  "credits_consumed": 0
}

enrich_contact

Resolves a person and returns professional attributes plus the company block. Email and phone are masked by default and free. The optional reveal array reveals fields inline and bills automatically.

Parameters

Cost

0 credits base. Inline reveal:["email"] costs 1 credit, reveal:["phone"] costs 3 credits, and reveal:["email","phone"] costs 4 credits. Unmatched fields are never charged.

Returns

title, seniority, department, linkedin_url, the full company block, email_available, phone_available, masked or revealed contact fields, reference_id, cached, credits_consumed, and credits_breakdown.

The reference_id is stable across calls and is the key consumed by the reveal tools. Store it in session state.

Sample response

A matched person with no contactable data is not charged, even when reveal is passed:

{
  "enrichment_status": "Person & Company Enriched",
  "title": "Chief Executive Officer",
  "department": "Management",
  "email_available": false,
  "email": null,
  "phone_available": false,
  "phone": null,
  "reference_id": "...",
  "credits_consumed": 0,
  "credits_breakdown": {}
}

reveal_email

Reveals the verified business email for a previously enriched contact.

Parameters

Cost

1 credit on first reveal. 0 credits if no email is matched. 0 credits on re-reveal by the same user.

Returns

email (string or null) and credits_consumed.

reveal_phone

Reveals both the direct-dial and the mobile phone number in a single charge.

Parameters

Cost

3 credits on first reveal. 0 credits if no phone is matched. 0 credits on re-reveal.

Returns

phone (direct-dial or null), mobile_phone (or null), and credits_consumed.

get_intent_signals

Returns domain-level buying-intent topics for a target company.

Parameters

Cost

1 credit when the company is matched, including when it currently has no surging topics. 0 credits only when the company cannot be matched, and 0 credits on a cache hit.

Returns

match_confidence, ls_domain_intent (a list of {topic, score} objects), cached, and credits_consumed.

get_usage_status

Returns plan, balance, and rate-limit state for the caller.

Parameters

Sample response

{
  "self_status": {
    "plan_tier": "builders_free",
    "balance": 67,
    "rate_limits": {
      "per_minute_limit": 30,
      "monthly_budget": 25
    },
    "sandbox": false
  }
}

Sample values only. The plan_tier string for the free tier is builders_free, published as Starter. On this tier, monthly_budget reports the daily allotment of 25 credits. The field name is a known misnomer for this tier — treat the value as the daily budget.

get_mcp_version_info

Returns server version and deprecation state. Use it to decide whether to upgrade a pinned URL or surface a deprecation warning.

Returns

current_major, current_minor, latest_major, deprecation_date, sunset_date, and breaking_since.

Live values are major 1, minor 0, with no deprecation or sunset currently set. When a deprecation is scheduled, deprecation_date and sunset_date populate and latest_major advances. Call this tool at the start of each session, since it is free and surfaces version changes early.

Credits and Billing

MCP usage draws from the same Leadspace credit budget as the rest of Sidekick. There is no separate MCP allowance. The per-action costs below apply on every plan.

Billing rules

credits_consumed equals the sum of credits_breakdown. There are no discounts or bonuses, so the breakdown can be quoted verbatim to users. Reveals are idempotent per (user + contact + field). Charges apply only to matched fields and matched companies. Your available balance, budget, and reset window are authoritative via get_usage_status.

Rate Limiting

The rate limit observed on the free Starter tier is 30 requests per minute. The free Starter tier includes 25 credits per day, use-it-or-lose-it, resetting daily. Paid plans (Solo, Pro, Enterprise) carry larger monthly credit allotments. Call get_usage_status for live limits, current usage, and balance.

Requests that exceed the per-minute window receive a 429 response. Call get_usage_status to check the window, then apply exponential backoff.

Caching and Idempotency

Enrichment and intent responses are cached and flagged with cached: true. Cache hits are never charged. Pass bypass_cache: true to force a fresh lookup.

Reveals are idempotent: the same user re-revealing the same field on the same contact pays 0 credits, so it is safe to re-call a reveal you have already performed, including inside retry loops. The reference_id for a contact is stable across calls and is the key the reveal tools consume.

Errors and Edge Cases

Integration Workflows

Prospect a contact

Call enrich_contact (free, masked), inspect email_available and phone_available, then reveal only what is needed. Prefer the inline reveal parameter to save a round-trip when you already know you want the field. Total for email and phone: 4 credits.

Prioritize accounts (account-led GTM)

Call enrich_account (free), then get_intent_signals (1 credit on match) to rank accounts by buying interest before spending reveal credits.

Budget-aware batch

Call get_usage_status (free) before a batch of reveals. Surface balance and monthly_budget to the user, and quote credits_breakdown after each paid call.

Dependency: enrich before you reveal

reveal_email and reveal_phone require the reference_id returned by a prior enrich_contact call. Store it in session state. Because reveals are idempotent per (user + contact + field), they are safe to call inside retry loops without double-charging.

Inline reveal (single call)

Pass the reveal parameter to enrich_contact to enrich and reveal in one round-trip instead of chaining separate reveal calls. Total cost is 4 credits: 0 for the enrichment, 1 for the email, and 3 for the phone.

{
  "tool": "enrich_contact",
  "input": {
    "linkedin_url": "https://www.linkedin.com/in/jane-doe",
    "reveal": ["email", "phone"]
  }
}

The response includes email, phone, mobile_phone, and credits_consumed: 4.

Troubleshooting

If none of the above resolve the issue, contact the Support team at support@leadspace.com.

Related Articles

• Leadspace MCP: User Guide
• Leadspace Bulk API v4: Technical Specifications
• What is Leadspace API service?