llms.txt

# LeadMagic API

> LeadMagic is a B2B data enrichment API. The live source of truth is `https://leadmagic.io/docs`, and current API routes are versioned under `/v1/...`.

Base URL: `https://api.leadmagic.io`

Authentication: send `X-API-Key` on every request.

Important: do not assume all responses use the same field naming style. Current public docs show a mix of snake_case and camelCase depending on the endpoint.

## Core Routes In This Repo

### Credits
- [Check Credits](https://leadmagic.io/docs/v1/reference/check-credits): `GET /v1/credits`

### People
- [Email Validation](https://leadmagic.io/docs/v1/reference/email-validation): `POST /v1/people/email-validation`
- [Email Finder](https://leadmagic.io/docs/v1/reference/email-finder): `POST /v1/people/email-finder`
- [Personal Email Finder](https://leadmagic.io/docs/v1/reference/personal-email-finder): `POST /v1/people/personal-email-finder`
- [B2B Social to Email](https://leadmagic.io/docs/v1/reference/profile-to-email): `POST /v1/people/b2b-profile-email`
- [Email to B2B Profile](https://leadmagic.io/docs/v1/reference/email-to-profile): `POST /v1/people/b2b-profile`
- [Mobile Finder](https://leadmagic.io/docs/v1/reference/mobile-finder): `POST /v1/people/mobile-finder`
- [Profile Search](https://leadmagic.io/docs/v1/reference/profile-search): `POST /v1/people/profile-search`
- [Role Finder](https://leadmagic.io/docs/v1/reference/role-finder): `POST /v1/people/role-finder`
- [Employee Finder](https://leadmagic.io/docs/v1/reference/employee-finder): `POST /v1/people/employee-finder`

### Companies
- [Company Search](https://leadmagic.io/docs/v1/reference/company-search): `POST /v1/companies/company-search`
- [Company Funding](https://leadmagic.io/docs/v1/reference/company-funding): `POST /v1/companies/company-funding`

### Jobs
- [Jobs Finder](https://leadmagic.io/docs/v1/reference/jobs-finder): `POST /v1/jobs/jobs-finder`
- [Job Country](https://leadmagic.io/docs/v1/reference/job-country): `GET /v1/jobs/countries`
- [Job Type](https://leadmagic.io/docs/v1/reference/job-types): `GET /v1/jobs/job-types`

### Ads
- [Google Ads Search](https://leadmagic.io/docs/v1/reference/google-ads-search): `POST /v1/ads/google-ads-search`
- [Meta Ads Search](https://leadmagic.io/docs/v1/reference/meta-ads-search): `POST /v1/ads/meta-ads-search`
- [B2B Ads Search](https://leadmagic.io/docs/v1/reference/b2b-ads-search): `POST /v1/ads/b2b-ads-search`
- [B2B Ad Details](https://leadmagic.io/docs/v1/reference/b2b-ad-details): `POST /v1/ads/b2b-ads-details`

## Current MCP Surface

The hosted LeadMagic MCP exposes:

- 10 tools (see README for the full mapping to REST endpoints)
- 1 shared docs resource: `leadmagic://docs`
- 2 built-in prompts (for example `account_research`, `contact_lookup`)

The MCP surface covers credits, people enrichment, company research, technographics, competitors, job-change detection, and role lookup.

Important distinction: ads endpoints and some jobs endpoints exist in the broader REST API and this snapshot, but they are not part of the current MCP tool surface.

## Hosted MCP Sign-In

- Entrypoint: `https://mcp.leadmagic.io/mcp` (streamable HTTP)
- Per-client install snippets (canonical): `https://mcp.leadmagic.io/clients`
- OAuth authorization server metadata: `https://mcp.leadmagic.io/.well-known/oauth-authorization-server`
- OAuth protected resource metadata: `https://mcp.leadmagic.io/.well-known/oauth-protected-resource/mcp`
- Registration endpoint (DCR): `https://mcp.leadmagic.io/oauth/register`
- OAuth scopes: `openid profile email offline_access`
- Static public OAuth client (no DCR): client ID `4b9eLjoGVCJ1Dvnc`, secret blank (PKCE, S256). This ID is public by design.
- API-key fallback header: `x-leadmagic-key: <YOUR_API_KEY>`
- Bearer fallback header: `Authorization: Bearer <YOUR_LEADMAGIC_TOKEN>`

Supported clients (all streamable-HTTP against the same URL): Cursor, Claude Desktop / Code / claude.ai, ChatGPT Developer Mode + Responses API, VS Code / GitHub Copilot, Windsurf, Zed, Cline, Roo Code, OpenCode, Gemini CLI, JetBrains IDEs, Amazon Q Developer, GitHub Copilot Coding Agent, Continue, Amp, Augment Code, Vercel AI SDK.

For Cursor specifically, prefer the official plugin at `https://github.com/LeadMagic/leadmagic-cursor-plugin` (ships `mcp.json`, rules, skills, agent, and commands). Manual alternative is a URL-only `.cursor/mcp.json` entry — Cursor v0.48+ handles OAuth + DCR internally.

## Docs-Only Endpoints Not Yet Modeled Here

- Analytics API
- Job Change Detector
- Technographics
- Competitors Search
- Job company types
- Job industries
- Job regions
- Credits helper endpoints like refresh and health

## Repository Files

- [README](README.md): Current repo guidance
- [llms-full.txt](llms-full.txt): Longer LLM-oriented reference
- [OpenAPI YAML](leadmagic-openapi-3.1.yaml): Local OpenAPI snapshot
- [OpenAPI JSON](leadmagic-openapi-3.1.json): Local JSON snapshot