# LeadMCP

> LeadMCP is a contact-data API and an MCP server for AI agents. An agent sends structured filters and gets a count, a page of contact rows, a file, or an enrichment answer.

API base URL: https://api.leadmcp.ai/v1
MCP server URL: https://mcp.leadmcp.ai
Contract version: 2026-09-19
Full reference in one file: https://docs.leadmcp.ai/llms-full.txt

## Docs

- [Overview](https://docs.leadmcp.ai): LeadMCP is a contact-data API and an MCP server for AI agents. An agent sends structured filters and gets a count, a page of contact rows, a file, or an enrichment answer.
- [Quickstart](https://docs.leadmcp.ai/get-started): Get a key and make the first call.
- [Worked examples](https://docs.leadmcp.ai/examples): Buyer briefs, and the calls an agent makes for each one.
- [Authentication](https://docs.leadmcp.ai/authentication): Send the key on every request.
- [The envelope](https://docs.leadmcp.ai/envelope): Every success answer has the same shape.
- [Filters](https://docs.leadmcp.ai/filters): Describe the audience you want.
- [Errors and warnings](https://docs.leadmcp.ai/errors): Read a failure and a partial answer.
- [Exports](https://docs.leadmcp.ai/exports): Deliver a list as a file.
- [Enrichment](https://docs.leadmcp.ai/enrichment): Match identifiers to stored rows.
- [Limits](https://docs.leadmcp.ai/limits): The caps on contact credits, requests and time.
- [All routes](https://docs.leadmcp.ai/routes): Every REST route, with what it does and what it costs.
- [Tools](https://docs.leadmcp.ai/mcp/tools): What your agent can do with the MCP server.
- [Connect a client](https://docs.leadmcp.ai/mcp/connect): Add the server to your agent.
- [Changelog](https://docs.leadmcp.ai/changelog): What changed in the contract.

## Routes

- [GET /account](https://docs.leadmcp.ai/account/get-account): Get account. Free.
- [GET /credits](https://docs.leadmcp.ai/credits/get-credits): Get credit balances. Free.
- [GET /health](https://docs.leadmcp.ai/health/get-health): Health check. Free.
- [GET /contacts/schema](https://docs.leadmcp.ai/contacts/get-contacts-schema): List columns. Free.
- [GET /contacts/schema/{column}/values](https://docs.leadmcp.ai/contacts/get-column-values): List column values. Free.
- [POST /contacts/count](https://docs.leadmcp.ai/contacts/count-contacts): Count matches. Free.
- [POST /contacts/search](https://docs.leadmcp.ai/contacts/search-contacts): Find contacts. Each returned contact costs one contact credit.
- [POST /exports](https://docs.leadmcp.ai/exports/start-export): Start an export. One contact credit per exported contact, charged on completion.
- [GET /exports/{id}](https://docs.leadmcp.ai/exports/get-export): Get an export. Free.
- [POST /enrichments](https://docs.leadmcp.ai/enrichments/enrich-contacts): Enrich contacts. One contact credit per stored match. A miss costs nothing.
- [GET /signals](https://docs.leadmcp.ai/signals/list-signals): list signals. Free.
- [POST /signals/collect](https://docs.leadmcp.ai/signals/collect-signals): collect signals. One premium credit per lead; holds twice the expected engagers, or exactly the requested company followers (without max_followers, at most the premium credits available). Premium credits are held before work starts, and a dry run is free.
- [GET /signals/collect/{id}](https://docs.leadmcp.ai/signals/get-collect): get collect status. Free.
- [POST /signals/alerts](https://docs.leadmcp.ai/signals/create-alert): create alert. One premium credit per new lead, held before each run. Premium credits are held before work starts, and a dry run is free.
- [GET /signals/alerts](https://docs.leadmcp.ai/signals/list-alerts): list alerts. Free.
- [GET /signals/alerts/{id}](https://docs.leadmcp.ai/signals/get-alert): get alert. Free.
- [PATCH /signals/alerts/{id}](https://docs.leadmcp.ai/signals/update-alert): update alert. Free.
- [DELETE /signals/alerts/{id}](https://docs.leadmcp.ai/signals/stop-alert): stop alert. Free.
- [POST /signals/alerts/{id}/poll](https://docs.leadmcp.ai/signals/poll-alert): poll alert. One premium credit per new lead. Premium credits are held before work starts, and a dry run is free.
- [POST /feedback](https://docs.leadmcp.ai/feedback/send-feedback): Send feedback. Free.
- [GET /companies/schema](https://docs.leadmcp.ai/companies/get-companies-schema): Get the company schema. Free.
- [GET /companies/schema/{column}/values](https://docs.leadmcp.ai/companies/get-company-column-values): List company column values. Free.
- [POST /companies/count](https://docs.leadmcp.ai/companies/count-companies): Count companies. Free.
- [POST /companies/search](https://docs.leadmcp.ai/companies/search-companies): Search companies. Each returned company costs one contact credit.
- [POST /companies/lookup](https://docs.leadmcp.ai/companies/lookup-companies): Look up companies. One contact credit per match. A miss costs nothing.
- [GET /keys](https://docs.leadmcp.ai/keys/list-api-keys): List API keys. Free.
- [POST /keys](https://docs.leadmcp.ai/keys/create-api-key): Create an API key. Free.
- [DELETE /keys/{id}](https://docs.leadmcp.ai/keys/revoke-api-key): Revoke an API key. Free.

## MCP tools

- [guide](https://docs.leadmcp.ai/mcp/tools#tools): Explains the workflow, the filter keys and the cost of each tool. Free.
- [count_matches](https://docs.leadmcp.ai/mcp/tools#tools): Counts the contacts that match a filter. Free.
- [find_contacts](https://docs.leadmcp.ai/mcp/tools#tools): Returns a page of contact rows for a filter. Each returned contact costs one contact credit.
- [get_values](https://docs.leadmcp.ai/mcp/tools#tools): Lists the allowed values of one closed-list column, with an optional search string. Free.
- [start_export](https://docs.leadmcp.ai/mcp/tools#tools): Starts a file job for a filter and answers with the job size (rows_available and rows_to_export). One contact credit per exported contact, charged on completion.
- [get_export](https://docs.leadmcp.ai/mcp/tools#tools): Polls one export job and returns its status. Poll every 3 to 5 seconds until status is completed. Then it returns a download URL on our own domain that needs no key and is valid 7 days from completion. The file is gzip-compressed (.csv.gz or .jsonl.gz): download it and gunzip it, or give the link to the person when you have no shell. An expired or gone file answers 410 with the code `export.expired`. Free.
- [enrich_contact](https://docs.leadmcp.ai/mcp/tools#tools): Matches up to 100 work emails, phone numbers or LinkedIn profile URLs to stored rows. One contact credit per stored match. A miss costs nothing.
- [get_credit_balance](https://docs.leadmcp.ai/mcp/tools#tools): Both meters, as separate objects. contact_credits: the plan caps, what is left this month and today, and the reset time. premium_credits: this month's allowance, used, held, available and the reset time. Premium credits pay for engagers and verified emails. Free.
- [list_signals](https://docs.leadmcp.ai/mcp/tools#tools): Every row has the same columns. Free.
- [collect_signals](https://docs.leadmcp.ai/mcp/tools#tools): Collects one profile, post or company page once. Company followers accept max_followers (minimum 100) and finish asynchronously. One premium credit per lead. One premium credit per lead; holds twice the expected engagers, or exactly the requested company followers (without max_followers, at most the premium credits available). Premium credits are held before work starts, and a dry run is free.
- [get_collect](https://docs.leadmcp.ai/mcp/tools#tools): Returns the status of one collect job: queued, running, completed or failed. It also returns the leads and contacts so far, the premium credits held and charged, and the list_signals arguments that read the rows. After collect_signals, call it every 30 to 60 seconds until status is completed or failed. Then read the rows with list_signals. Free.
- [estimate_signals](https://docs.leadmcp.ai/mcp/tools#tools): Returns units (expected engagers or company followers), premium_credits (premium credits reserved), available and sufficient. Includes upgrade_url only when insufficient. Company pages accept max_followers. Free.
- [create_alert](https://docs.leadmcp.ai/mcp/tools#tools): An alert is a source of signals. Read them with `list_signals`. Watches one profile or post daily. Paid plans only, at most 100 active alerts. Answers 403 plan.required for free plans or 403 alerts.limit_reached when the cap is reached. One premium credit per new lead, held before each run. Premium credits are held before work starts, and a dry run is free.
- [list_alerts](https://docs.leadmcp.ai/mcp/tools#tools): An alert is a source of signals. Read them with `list_signals`. Lists the account's alerts with signal and lead counts and the last job state. Free.
- [get_alert](https://docs.leadmcp.ai/mcp/tools#tools): An alert is a source of signals. Read them with `list_signals`. Returns one alert and its last job. Free.
- [update_alert](https://docs.leadmcp.ai/mcp/tools#tools): An alert is a source of signals. Read them with `list_signals`. Pauses, resumes or changes the cadence of one alert. Free.
- [stop_alert](https://docs.leadmcp.ai/mcp/tools#tools): An alert is a source of signals. Read them with `list_signals`. Removes one alert. Its signals stay. Free.
- [poll_alert](https://docs.leadmcp.ai/mcp/tools#tools): An alert is a source of signals. Read them with `list_signals`. Runs one alert now. One premium credit per new lead. Answers 409 while a run is in progress. Premium credits are held before work starts, and a dry run is free.
- [send_feedback](https://docs.leadmcp.ai/mcp/tools#tools): Report a problem to the LeadMCP team: a missing feature or filter, a bug, wrong data in a row, or an unclear error. Send the request_id from the response of the call that went wrong. Call it once for each problem, not after every call. It is free. Free.
- [count_companies](https://docs.leadmcp.ai/mcp/tools#tools): Counts the companies that match a company filter. Free.
- [find_companies](https://docs.leadmcp.ai/mcp/tools#tools): Returns a page of company records for a company filter. Each returned company costs one contact credit.
- [get_companies](https://docs.leadmcp.ai/mcp/tools#tools): Matches up to 100 company ids, domains or company LinkedIn URLs to company records. One contact credit per match. A miss costs nothing.
- [create_api_key](https://docs.leadmcp.ai/mcp/tools#tools): Creates the account's one API key for scripts and tools without OAuth, and returns the key once. An account has one active key: while one exists the answer is 409 key.limit_reached, so call revoke_api_key first. Works only in an OAuth session. Free.
- [list_api_keys](https://docs.leadmcp.ai/mcp/tools#tools): Lists the account's active API key with its id, name, created_at and last_used_at. Never returns the key itself. Works only in an OAuth session. Free.
- [revoke_api_key](https://docs.leadmcp.ai/mcp/tools#tools): Revokes one API key by id at once. Free.