The contact database, as tools your agent calls

• Describe the audience

  Your agent states the audience in structured filters, and writes a where expression over the same columns the contract publishes. There is no query language to learn.

• Size it before it spends

  A count is free and exact. The agent can try a filter, widen it, and try again before it reads a single row.

• Read the rows, page by page

  A search hands back a page of rows and a cursor. The agent follows the cursor until it holds what it asked for.

• Keep the list clean

  Exclude the people and the companies you already own, and cap how many rows one company can contribute.

• Read the career signals

  Each contact carries short labels about the career: a recent job change, a founder, time at a public company. Filter on them like any other value.

• Take the audience as a file

  For a large audience the agent starts an export instead, polls the job, and downloads a file of up to 50,000 rows.

• Match a person you already know

  Give a work email or a profile URL, and the agent gets the stored row back. A miss costs nothing.

• One flat plan behind it

  One price a month with unlimited leads. Counts are free, and phones come in the row.

• Explains the workflow, the filter keys and the cost of each tool; list_tools names it first.guide
• Counts the contacts that match a filter; free, and exact inside its 3 s budget.count_matches
• Returns a page of contact rows for a filter; 50 rows by default, 500 at most. Each returned contact costs one contact credit.find_contacts
• Lists the allowed values of one closed-list column, with an optional search string; free.get_values
• 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. A filter that matches nothing is refused with 400 export.no_matches, free, and no job is created.start_export
• 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`.get_export
• 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. Shared phones also cost nothing and return reason ambiguous. An input that is no email, phone or LinkedIn profile URL returns reason invalid and costs nothing. The forms 'mailto:' and 'Name <email>' are accepted. Send the full profile URL. To find a person by name, call find_contacts with domains and a where leaf {field: name, op: contains}.enrich_contact
• 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; stored contact delivery uses contact credits. Free.get_credit_balance
• Every row has the same columns; kind-specific fields sit in details. A row whose LinkedIn URL matches a stored contact carries it in contact, and contact_status says why a row has none. Reading is free. To read one source, send source_type (alert or collect), and optionally source_id (the alert id or the collect job id); the cursor keeps the filter.list_signals
• Collects one profile, post or company page once. Company followers accept max_followers (minimum 100) and finish asynchronously. 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). An engager or follower we hold arrives with contact data and costs one contact credit, charged once when the row is collected. An unknown one costs nothing extra and arrives with contact: null. With wait, engagement estimates of 500 or fewer finish inline. Otherwise poll get_collect with job.id every 30 to 60 seconds until status is completed, then read the rows with list_signals.collect_signals
• 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.get_collect
• 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; alerts support profiles and posts. Writes nothing. Free.estimate_signals
• 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.create_alert
• 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.list_alerts
• An alert is a source of signals. Read them with `list_signals`. Returns one alert and its last job. Free.get_alert
• An alert is a source of signals. Read them with `list_signals`. Pauses, resumes or changes the cadence of one alert. Free.update_alert
• An alert is a source of signals. Read them with `list_signals`. Removes one alert. Its signals stay. Free.stop_alert
• 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.poll_alert
• 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.send_feedback
• Counts the companies that match a company filter; free, and exact inside its 3 s budget.count_companies
• Returns a page of company records for a company filter; 50 by default, 500 at most. Each returned company costs one contact credit. Send the ids to find_contacts in company_ids to find the people.find_companies
• Matches up to 100 company ids, domains or company LinkedIn URLs to company records; one contact credit per match. A miss costs nothing.get_companies
• 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.create_api_key
• 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.list_api_keys
• Revokes one API key by id at once; every call with it fails from then on. An unknown id answers 404 key.not_found. Works only in an OAuth session. Free.revoke_api_key

Server URLhttps://mcp.leadmcp.ai

Claude appOAuth, one click

Add a custom connector in Settings, then Connectors. Paste the server URL, keep the detected options, and approve. That is the whole setup.

ChatGPTOAuth, one click

Add an MCP server in Settings, then Plugins. Pick Streamable HTTP, paste the server URL, leave the bearer token and the headers empty, then authenticate and approve.

Claude CodeDevice grant

Register the client, open the verification URL, type the user code, and approve. Poll for the token, then add the server with the token on the Authorization header.

CodexDevice grant

Run the same device grant, then add the server to the client config file with the token on the Authorization header.

CursorBearer key

Add a global MCP server and put your API key on the Authorization header of the server entry.

REST, and any other toolBearer key

Send the key as a bearer token on every request. Size the job with a count: a count costs nothing and tells you how big the audience is.

The connect page gives the exact steps, the commands and the config files.

1. 01

   guide Read the guide

   The agent calls guide first. It gets the workflow, the filter keys and the cost of each tool before it acts.

2. 02

   count_matches A country, a seniority and a function

   The agent sizes the audience. A count is free, so it can try a filter, widen it, and try again.

3. 03

   get_values Exclude a competitor and an industry

   The agent reads the allowed values of a closed list, so it filters on a real slug and never on a guess.

4. 04

   find_contacts The second page, by cursor

   The agent reads a page of rows, then follows the cursor for the next page. Phones come in the row.

5. 05

   start_export Take the audience as a file

   For a large audience the agent starts an export instead, then polls the job and downloads the file.

6. 06

   enrich_contact Enrichment by LinkedIn URL

   Given a list of profile URLs or work emails, the agent matches them to stored rows. A miss costs nothing.

Read every worked example on the examples page.