Leadspace Sidekick MCP: Developer Guide – Leadspace

The Leadspace Sidekick MCP server is 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. Use a client with remote-server support (Claude web, desktop and Code, Cursor, Codex, ChatGPT, VS Code and others). The mcp-remote bridge is not supported: it registers a new client on first connect, which Leadspace's sign-in service does not allow.

Authentication

OAuth 2.1 with a browser-based sign-in that starts automatically on first connection. Claude and ChatGPT identify themselves to Leadspace's sign-in service, so leave any Client ID and Client Secret fields blank. Cursor, and any other client that asks for one, uses Leadspace's public client ID Yy6qUuX1EAz2hejQ4JUXFnMeyOcYPelU with no secret.

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 > Name: Leadspace Sidekick, paste the endpoint > leave OAuth fields blank > Connect > sign in.
Claude Code	`claude mcp add --transport http leadspace-sidekick https://sidekick.leadspace.com/mcp/v1`, then `/mcp` > leadspace-sidekick > Authenticate.
Cursor	In `mcp.json`: `"leadspace-sidekick": { "url": "https://sidekick.leadspace.com/mcp/v1", "auth": { "CLIENT_ID": "Yy6qUuX1EAz2hejQ4JUXFnMeyOcYPelU" } }` > Connect > sign in.
Codex	`codex mcp add leadspace-sidekick --url https://sidekick.leadspace.com/mcp/v1`, then `codex mcp login leadspace-sidekick`.
ChatGPT	On the web: Plugins > Browse directory > Add custom MCP server > Name: Leadspace Sidekick, Server URL: the endpoint, Authentication: OAuth, Advanced OAuth settings unchanged > Create as a plugin > Connect > sign in > Accept. In a chat, type @ and choose Leadspace Sidekick.
VS Code, n8n, others	Add a remote (HTTP) MCP server pointing at the endpoint. If the client asks for a client ID, use the public one above.

Plans and access

Tool family	Available on
`sk_` tools (7): single-record enrichment, reveals, intent, usage, version	All plans, including Starter
`cc_` tools (54): search, profiles, signals, lists, export, CRM, admin	All plans, including Starter, within each plan's limits (see the notes below)

cc_ tools enforce the same permissions and plan limits as the website, including role-based list visibility, list caps, export limits, tier-gated filters (named in filters_not_in_plan), Similar Companies lists and list import on Solo and above, CRM export on Pro and above, Signals Intelligence tools on Enterprise with the Signals Intelligence add-on, 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 that describe how the tools fit together (the chaining metadata, cc_ versus sk_ tools, the confirm contract and each error class) and ask the model to quote the cost and get the user's go-ahead before the first call that spends credits.
Tool titles and annotations: every tool has a title and carries readOnlyHint, destructiveHint, idempotentHint and openWorldHint. readOnlyHint is false for tools that change the workspace or can spend credits (the four reveals and sk_enrich_contact); destructiveHint is true for tools that remove or overwrite data (cc_delete_list, cc_update_list, cc_update_user, cc_deactivate_user).
Tool metadata: _meta["leadspace/requires"] names a tool's prerequisites, _meta["leadspace/next"] the tools that usually follow it, and _meta["leadspace/free"] marks free 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, the result says what the call cost. sk_enrich_contact, sk_reveal_email and sk_reveal_phone return credits_consumed, the credits that call charged (0 when nothing was charged); sk_enrich_contact also returns credits_breakdown, which always adds up to it. cc_reveal_email and cc_reveal_phones return balance_after, the caller's credit balance after the reveal.

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

`cc_` tools (all plans)

Area	Tools	Notes
Identity and plan	`cc_whoami`, `cc_get_my_permissions`, `cc_get_plan_usage`, `cc_get_workspace_company`, `cc_get_target_audience`, `cc_get_tracked_topics`, `cc_set_target_audience`*	Tracked topics (contact topics, company topics, competitors) are Solo and above. Setting the Target Audience is Admin or Co-Admin only and uses the `confirm` flag
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
Signals Intelligence	`cc_get_signals_overview`, `cc_get_signals_shortlist`, `cc_get_signals_account`	Enterprise with the Signals Intelligence add-on; the overview funnel, today's shortlist, and one account's why-now and people to reach
Reveals	`cc_reveal_cost_preview`, `cc_reveal_email`, `cc_reveal_phones`	Preview is free (up to 200 pids); email 1, phones 3
Watch list	`cc_update_watch_list`*	The website's ★: add or remove up to 100 companies or contacts per call
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_create_list`, `cc_create_similar_list`, `cc_import_list`, `cc_rerun_match`, `cc_update_list`, `cc_delete_list`	Same visibility and record caps as the website. Similar Companies lists (5+ seed companies) and imports are Solo and above; they, and re-run match, build in the background with `status: processing`
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.
cc_set_target_audience returns the whole change (every field and what it replaces) before saving.

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 cc_ 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
A filter or feature outside the plan	Searches, lists and exports apply the rest and name the skipped filters in `filters_not_in_plan`; a list or export over the plan's cap is refused with the plan's own limit
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

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.

Lookalikes and imports

cc_create_similar_list with at least 5 seed companies, or cc_import_list with the user's rows and a column mapping (Solo and above). cc_rerun_match refreshes a finished import into a new list.
Poll cc_get_list_details until the status is no longer processing, then read with cc_get_list_rows.

Work today's accounts (Signals Intelligence)

cc_get_signals_overview for the funnel, then cc_get_signals_shortlist for the accounts ready for outreach.
cc_get_signals_account for why now and who to reach, then reveal the chosen people.

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	Allow pop-ups for the client
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
Cursor can't sign in	No client ID in `mcp.json`	Add `"auth": { "CLIENT_ID": "Yy6qUuX1EAz2hejQ4JUXFnMeyOcYPelU" }` next to `"url"`
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.