MCP tools and what they cost

The MCP server is a thin, honest wrapper over the Generect API. Two rules make it safe to hand to an autonomous agent:

Sizing an audience is free. You can learn how many people match an ICP, and what pulling them would cost, without spending anything.
Every response reports what it actually cost. Each tool returns a cost block containing the API’s own meta.amount_charged, so an agent telling a human what it spent is quoting the biller, not guessing.

Requires MCP server 0.9.0 or newer for resources, prompts and the vocabulary guard; the tools themselves work from 0.7.0. Remote users (https://mcp.generect.com/mcp) are always on the deployed version. Local users should run npx generect-ultimate-mcp@latest.

Free tools

Tool	What it gives you
`count_leads`	How many leads match, plus the cost of the next step at your account’s rates
`preview_leads` with `count_only: true`	A second opinion on the count from the Preview index. Free — and the two indexes do disagree, so it is worth asking both
`count_companies`	The same, for companies
`get_balance`	Balance and your real per-operation prices. `include_usage` adds spend broken down by operation; `include_token_analytics` adds per-API-token request counts, which answers “which integration is making these calls?”
`get_bulk_job`	Status and results of a bulk job (the work was billed at submit time)
`manage_webhooks`	Register, list, update, delete or test a webhook endpoint
`health`	Liveness and credential check — touches no data endpoint, safe for monitors

Billable tools

Tool	Billed
`preview_leads`	$0.002 per returned row — the cheapest way to see real people
`search_leads`	per returned row
`search_companies`	per returned row
`enrich_lead` / `get_lead_by_url`	per record found (not found is free)
`enrich_company`	per record found (not found is free)
`generate_email`	per valid email found (a miss is free)
`validate_email`	per email submitted — every address, whatever the verdict
`find_phone`	per phone found — the most expensive operation
`start_bulk_job`	per record, and the worst case is reserved at submit time

Exact per-operation prices for your account are in billing settings, and get_balance returns them too. See Pricing for the list rates.

Filter values are matched exactly — and two of them are not validated

This is the most expensive thing to get wrong, so it is worth stating plainly. The search endpoints do not validate all filters the same way:

Filter	An unknown value
`locations`, `company_headcounts`, `company_types`	rejected with `400`, naming the field
`company_industries`, `seniorities`	accepted — 0 results, no charge, no error

company_industries: ["Fintech"] is not a LinkedIn industry, so it matches nothing and you get a perfectly successful count of zero. That is indistinguishable from a real empty audience, and it is how an agent ends up telling a user “there is nobody like that” when the truth is “that is not the name of an industry”. From 0.9.0 the MCP server checks these values before it sends anything:

an unknown industry, headcount bucket or company type is refused locally, with the closest valid names — Fintech → Financial Services, 50-200 → 51-200. Nothing is sent and nothing is charged;
a value that is merely mis-spelled or mis-cased is corrected (software development → Software Development), because matching is exact;
an unknown seniority or job function is a warning rather than a refusal: the engine does match loosely (Owner finds people even though the canonical label is Owner / Partner);
allow_unlisted_values: true overrides the check, for the case where the API has gained a value the server’s snapshot does not have yet.

Resources

The vocabularies are exposed as MCP resources, so a client can read the exact list once instead of guessing:

Resource	Contents
`generect://vocabulary/industries`	all 434 industry names, each with its parent
`generect://vocabulary/seniorities`	canonical seniority labels
`generect://vocabulary/functions`	job functions (realtime only)
`generect://vocabulary/company-types`	company types
`generect://vocabulary/headcounts`	headcount buckets
`generect://vocabulary/follower-ranges`	follower buckets (realtime only)
`generect://account/pricing`	your real per-operation prices
`generect://account/balance`	balance and month-to-date usage

Reading a resource is free and touches no data endpoint.

Prompts

The server also ships workflow prompts, which appear as slash commands in clients that support them: size_an_audience, build_prospect_list, enrich_my_list, spend_report. Each starts from the free step.

Spend ceiling

A row cap bounds how many results you get, not how much you pay — the per-row price depends on the mode and your tier. So any call whose worst case exceeds the server’s per-call ceiling (default $5, MCP_MAX_SPEND_PER_CALL) is refused with the exact figure, and has to be repeated with confirm_spend_usd set to at least that amount. This is checked before start_bulk_job submits, because a bulk job reserves its whole cost at submit time and cannot be called back.

Database or realtime

Every search and enrich exists in two modes — cached database (sub-second, cheaper, free counts, core filters) and live realtime (5–60s, pricier, billable counts, every filter). See Database vs Real-time. Tools take a mode parameter:

`mode`	Behaviour
`auto` (default)	Tries the cheap cached path. Escalates to realtime only if the API reports that a filter you passed does not exist there — and says so in the response.
`database`	Never escalates. An unsupported filter comes back as an error, not a larger bill.
`realtime`	Goes straight to the live index.

Counting is deliberately stricter: a realtime count costs money, so count_leads and count_companies never run one implicitly. If your filters need the live index, the tool returns the blocking filter names and the price, and waits for you to ask again with mode: "realtime".

The order to call things in

read generect://vocabulary/industries   free            → get the filter names exactly right
count_leads                             free            → is this audience big enough to be worth anything?
preview_leads                           $0.002/row      → who is actually in it? keep the ids that fit
search_leads                            per row         → pull only the rows you decided to keep
generate_email                          per valid email → contact details for those ids only
get_balance                             free            → report the exact spend back to the user

Records carry a stable id across preview, search and enrich, so once a lead is in your list you never have to search for them again — pass the id to enrich_lead, generate_email or find_phone directly.

For repeatable or scheduled work, submit up to 50 records with start_bulk_job and register a webhook with manage_webhooks instead of polling. A submitted job runs to completion even if your balance later hits zero, because its cost was reserved at submit time — so only submit lists that have been approved.

When to use the REST API instead

MCP is the right surface when a model is choosing what to fetch. Call the REST API directly when you need something MCP deliberately does not do:

pulling more than 100 rows in one request
pipelines with no model in the loop (nightly syncs, CRM backfills)
your own retry, concurrency and storage policy

​Free tools

​Billable tools

​Filter values are matched exactly — and two of them are not validated

​Resources

​Prompts

​Spend ceiling

​Database or realtime

​The order to call things in

​When to use the REST API instead

Free tools

Billable tools

Filter values are matched exactly — and two of them are not validated

Resources

Prompts

Spend ceiling

Database or realtime

The order to call things in

When to use the REST API instead