Leadspace MCP: Developer Guide – Leadspace

Leadspace offers a Model Context Protocol (MCP) server that exposes the Leadspace GTM Data Intelligence Cloud to any MCP-compatible AI client, such as Claude, Cursor, VS Code, n8n, Codex, ChatGPT or a custom LLM pipeline, as tools callable in natural language. This article covers the technical specification for connecting to and operating the server.

Tools are discovered at connection time through the standard MCP tools/list handshake. A client sees the tool set its account is entitled to, without any configuration.

Setup

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

Sign up at sidekick.leadspace.com with a work email. Personal email domains are rejected.
Use that login to authenticate the MCP server.

An existing Leadspace Sidekick account works as is. API-key authentication is not supported: every client authenticates through the same browser-based OAuth sign-in.

Connection

Endpoint

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

Use this address exactly as shown.

Transport

Streamable HTTP over HTTPS, as defined in the MCP specification. Clients with native remote-server support (Claude web, desktop and Code, Cursor, Codex, ChatGPT) connect directly. Clients that only support local stdio servers can use the mcp-remote bridge, which needs Node.js:

npx -y mcp-remote https://sidekick.leadspace.com/mcp/v1

Authentication

OAuth 2.1 with a browser-based sign-in that starts automatically on first connection. Leave any Client ID and Client Secret fields blank; client registration is handled for you.

Item	Value
Protected resource metadata (RFC 9728)	`https://sidekick.leadspace.com/.well-known/oauth-protected-resource`
Authorization server	`https://auth-prod.leadspace.com/`
Scopes	`openid profile email offline_access`
Token delivery	`Authorization: Bearer` header
Access token lifetime	About 24 hours; refresh tokens rotate automatically (requires `offline_access`)

The first unauthenticated request returns 401 with a WWW-Authenticate header pointing at the metadata. This is expected OAuth discovery, not a failure.
A browser window opens. The user signs in with their Leadspace work email and password.
The client stores the access and refresh tokens and reports Connected.

Identity and workspace always come from the token, never from tool arguments. The user always completes sign-in; never pass tokens or credentials to an agent.

Version

The server is major version 1. Call sk_get_mcp_version_info for the live major and minor version, deprecation and sunset dates, and a note when tool descriptions have changed.

Client setup

Client	Setup
Claude web / desktop	Settings > Connectors > Add custom connector > paste the endpoint > leave OAuth fields blank > Connect > sign in.
Claude Code	`claude mcp add --transport http leadspace https://sidekick.leadspace.com/mcp/v1`, then `/mcp` > leadspace > Authenticate.
Cursor	Settings > MCP > Add server > paste the endpoint > authenticate.
Codex	`codex mcp add leadspace --url https://sidekick.leadspace.com/mcp/v1`, then `codex mcp login leadspace`.
ChatGPT	Requires Developer Mode. Settings > Apps > Create > URL: the endpoint, Authentication: OAuth > Create > sign in. Write tools are available on ChatGPT Business, Enterprise and Edu.
VS Code, n8n, others	Add a remote (HTTP) MCP server pointing at the endpoint, or use the `mcp-remote` bridge above.

Plans and access

Tool family	Available on
`sk_` Sidekick tools (7): single-record enrichment, reveals, intent, usage, version	All plans, including Starter
`cc_` Command Center tools (50): search, profiles, signals, lists, export, CRM, admin	Pro plan and above

Command Center tools enforce the same permissions as the website, including role-based list visibility, export limits and admin-only actions. A tool refuses exactly where the website would.
Some features also need workspace setup. For example, buying groups need Target Audience personas, and CRM presence needs a synced CRM with CRM Insights enabled.
cc_get_my_permissions returns the caller's entitlements and list capacity so an agent can check before acting.
Organizations on a No-AI contract receive ai_disabled from every tool.

Agent guidance served by the server

Operating guide: initialize returns instructions telling the model to act without asking which tool to use, chain tools using their metadata, confirm only before a charge or a destructive write, and recover from each error class.
Tool annotations: every tool carries readOnlyHint, destructiveHint, idempotentHint and openWorldHint.
Tool metadata: _meta["leadspace/requires"] names a tool's prerequisites and _meta["leadspace/free"] marks free tools. Sidekick tools also list next_tools.
Starter prompts: available through prompts/list.
Tool-list changes: the server does not send notifications/tools/list_changed (it advertises listChanged: false). Reconnect to pick up new or changed tools.

Tool reference

Each tool's full schema, when-to-use guidance and example asks are returned by tools/list. All tools are free unless the table says otherwise. For paid tools, credits_consumed is the total charged, and it always equals the sum of credits_breakdown.

Sidekick tools (all plans)

Tool	Purpose	Key inputs	Cost
`sk_enrich_account`	Firmographics, SIC and NAICS codes, HQ, logo and corporate hierarchy (site / domestic ultimate / global ultimate)	`company_website`, `company_name` or `company_linkedin_url`	Free
`sk_enrich_contact`	Title, department, LinkedIn and company block; email and phone masked. Returns a stable `reference_id`.	`linkedin_url`, `email`, or `first_name` + `last_name` (+ company); optional `reveal`	Free; inline reveal: email 1, phone 3, both 4
`sk_reveal_email`	Verified business email	`reference_id`	1
`sk_reveal_phone`	Direct-dial and mobile, together	`reference_id`	3
`sk_get_intent_signals`	Intent topics with 0–100 strength	`company_website`, or `company_name` + `country`	Free
`sk_get_usage_status`	Plan, balance, budget and refresh period	none	Free
`sk_get_mcp_version_info`	Version, deprecation and sunset state	none	Free

Command Center tools (Pro and above)

Area	Tools	Notes
Identity and plan	`cc_whoami`, `cc_get_my_permissions`, `cc_get_plan_usage`, `cc_get_workspace_company`, `cc_get_target_audience`	Read-only
Search	`cc_search_people`, `cc_search_companies`, `cc_get_filter_options`, `cc_get_boolean_syntax_help`	Paginated (max 50 per page, cursor). Use `cc_get_filter_options` for exact taxonomy values.
Records and research	`cc_get_person_profile`, `cc_get_company_profile`, `cc_get_similar_contacts`, `cc_get_buying_signals`, `cc_get_buying_group`, `cc_get_linkedin_activity`, `cc_get_crm_presence`	Contact data stays masked unless already revealed
Reveals	`cc_reveal_cost_preview`, `cc_reveal_email`, `cc_reveal_phones`	Preview is free (up to 200 pids); email 1, phones 3
Lists	`cc_get_my_lists`, `cc_get_list_details`, `cc_get_list_rows`, `cc_get_list_snapshots`, `cc_get_snapshot_rows`, `cc_get_list_dependencies`, `cc_get_saved_contacts`, `cc_create_list`, `cc_update_list`, `cc_delete_list`, `cc_save_contacts`, `cc_unsave_contacts`, `cc_save_companies`, `cc_unsave_companies`*	Same visibility and record caps as the website
Export and CRM	`cc_list_export_destinations`, `cc_get_export_status`, `cc_get_crm_send_status`, `cc_start_export`, `cc_send_export_to_crm`	CSV, Salesforce (Contact or Lead) or HubSpot; uses the monthly export quota and saved field mapping
Notifications	`cc_list_notifications`, `cc_get_priority_alerts`, `cc_mark_notification_read`, `cc_mark_all_notifications_read`	The caller's own notifications only
Administration	`cc_list_users`, `cc_get_user`, `cc_list_roles`, `cc_list_teams`, `cc_list_audit_events`, `cc_invite_user`, `cc_update_user`, `cc_deactivate_user`*	Admin or Co-Admin as on the website; the audit log is admin-only (30/60/90 days)

* Write tool: it changes data in the workspace.

Confirmation pattern

Consequential actions use a two-step confirm flag. The first call changes nothing and returns what would happen. The agent shows that to the user, then calls again with confirm: true.

cc_delete_list names the lists the delete would break.
cc_invite_user sends a real email and uses a seat; cc_deactivate_user removes access.
cc_start_export with reveals returns confirmation_required with the cost and balance before charging.

Credits and billing

MCP usage draws from the account's single credit balance, shared with the Sidekick extension and the Leadspace website. There is no separate MCP allowance.
Pay once: a contact field revealed on any surface is free to show again on any other.
No charge for unmatched fields or cache hits. Account enrichment, contact enrichment, intent signals, search and all Command Center reads are free.
Starter (plan_tier: builders_free): 25 credits per day, reset at midnight UTC, no rollover. Paid plans refresh monthly.
Bonus credits survive the refresh and are spent after the period budget, so balance can exceed budget.
sk_get_usage_status returns balance, budget, budget_used and refresh_period (daily or monthly). monthly_budget and monthly_used are deprecated aliases.
cc_get_plan_usage adds seats and renewal (for admins) and the export quota.

{
  "self_status": {
    "plan_tier": "builders_free",
    "balance": 30,
    "refresh_period": "daily",
    "budget": 25,
    "budget_used": 25,
    "overrides_active": false
  }
}

Rate limiting

Limits apply per user and per tool. Reveals share the website's reveal limit, so an agent can't spend credits faster than the reveal button. A request over the limit is refused with a message containing retry_after_seconds and the statement that nothing was charged. Wait the given time before retrying, and space out bursts of calls. sk_get_usage_status does not report rate-limit state.

Caching and idempotency

Enrichment and intent responses are cached and flagged cached: true; cache hits are never charged. Pass bypass_cache: true to force a fresh lookup. Reveals are idempotent per contact and field, so retrying a reveal never double-charges. reference_id is stable across calls.

Errors and edge cases

Situation	Behavior
Unauthenticated request	`401` with `WWW-Authenticate`: expected OAuth discovery
Plan doesn't include Command Center	`cc_` tools are refused with an upgrade message; `sk_` tools keep working
Insufficient credits	The paid call is refused with the cost and the balance. If an `sk_enrich_contact` call includes an unaffordable `reveal`, the whole call is refused, so retry without `reveal` to get the free enrichment.
Rate limit exceeded	Refused with `retry_after_seconds`; nothing charged
Person not matched	Company-only enrichment with null person fields; reveals return null at 0 cost
Field not on file	`email_available` / `phone_available` is false; the reveal returns null and charges 0
Country LinkedIn subdomains	Normalize `au.linkedin.com/in/…` (and similar) to `www.linkedin.com/in/…` before calling
Empty results with a state field	Tools such as `cc_get_similar_contacts` return an empty list plus `state` and `note` when a service is degraded. Only `state: "full"` with no rows means none were found.
Result size and timeout	Tool results are kept under about 25,000 tokens; handlers complete within 5 minutes

Integration workflows

Enrich and reveal a known contact (all plans)

sk_enrich_contact (free): check email_available / phone_available and store reference_id.
sk_reveal_email (1) and/or sk_reveal_phone (3). Or pass reveal: ["email","phone"] in step 1 for a single call (4 credits).

Prospect from search (Pro and above)

cc_get_filter_options, then cc_search_people or cc_search_companies (free).
cc_get_person_profile, cc_get_buying_signals or cc_get_buying_group for context (free).
cc_reveal_cost_preview on the chosen pids, check affordable, then cc_reveal_email / cc_reveal_phones.
cc_create_list with the same filters, or cc_start_export to CSV or a CRM.

Budget-aware batch

Call sk_get_usage_status (or cc_reveal_cost_preview) before a batch. Show the user the balance and total cost, and quote credits_breakdown after each paid call.

Troubleshooting

Symptom	Likely cause	Resolution
Tools not visible after connecting	OAuth sign-in not completed	Reconnect and finish the browser sign-in
New tools missing	Client cached the old tool list	Disconnect and reconnect
OAuth prompt doesn't appear	Pop-up blocked, or Node.js missing for `mcp-remote`	Allow pop-ups; check that `npx` is available
Repeated sign-ins	Refresh token not issued	Ensure the client requests `offline_access`
`401` on a tool call	Access token expired	Reconnect; sign-in triggers automatically
Command Center tools refused	Plan below Pro	Upgrade, or use the `sk_` tools
Search returns 0 rows	Filter value not in the taxonomy	Use exact values from `cc_get_filter_options`
Balance lower than expected	Agent loop calling paid tools	Add usage guards; reveals are idempotent

If none of these resolve the issue, contact support@leadspace.com.