LeadMagic — MCP integration

Prefer the hosted MCP over hand-rolled curl in agent sessions: OAuth (no key in shell history), server-side token handling, and composite tools that replace multi-call chains.

• URL: https://mcp.leadmagic.io/mcp
• Setup docs: leadmagic.io/docs/mcp/introduction
• Plugin (bundles this + skills + hooks): LeadMagic/leadmagic-skills

Config

Claude Code: claude mcp add --transport http leadmagic https://mcp.leadmagic.io/mcp

Cursor configuration (other clients use their own formats; consult the setup docs):

{
  "mcpServers": {
    "leadmagic": { "url": "https://mcp.leadmagic.io/mcp" }
  }
}

Claude web / desktop custom connector: URL https://mcp.leadmagic.io/mcp. Per-client steps: mcp.leadmagic.io/clients.

New users: sign up at app.leadmagic.io, run one thing in the app (e.g. a first sheet in Sheet Enrichment — see the sheets skill), then connect the MCP. OAuth signs the client into a workspace; pick the one that owns the user's sheets and credits.

Complete OAuth in the browser on first use. 401 later → reconnect OAuth in the client (do not add a REST API key to this OAuth configuration). 402 → credits/billing.

Tool → REST map (core)

Ads and competitor tools are currently paused on hosted MCP. Custom HTTP request columns are configured and run in the LeadMagic app; hosted MCP exposes no arbitrary outbound HTTP tools.

Sheets tools only appear when the signed-in workspace has Sheets (paid plan). If they're missing, check the plan and the workspace chosen during OAuth, then reconnect.

Usage rules

• Prefer composites (account_intel, enrich_contact, find_decision_makers) over long primitive chains.
• Who holds one role or title at a company → find_people_by_role first (2 credits if found, free on a miss). Use search_people or find_company_employees only for lists; if Role Finder finds no one, report the miss instead of searching for the role.
• Free first: check_credit_balance + preview_cost before expensive or bulk work.
• One record → single tools; CSV/list → bulk path or a sheet; poll get_bulk_job_status ≥45s apart.
• Single-record lookups run directly. Every paid sheet run, including small samples, runs of 5 credits or less, and AI using the user's own provider key, requires an exact quote and explicit user approval. Only verified free sheet runs (zero LeadMagic credits and no external provider billing) start immediately; unknown quotes cannot start. Bulk jobs, paid sheet runs, imports, pushes, and deletes return needs_confirmation + confirmation_token first. Show the credit cost and provider billing summary, resend the identical arguments with the token only after the user agrees, and never invent a token.
• Claude Code names plugin-bundled tools mcp__plugin_leadmagic_leadmagic__<tool> and hand-added ones mcp__leadmagic__<tool>. Permission rules and hooks must match both (the plugin's approval hook does).
• Pass company_domain (e.g. stripe.com) when identifying companies.