> ## Documentation Index > Fetch the complete documentation index at: https://docs.generect.com/llms.txt > Use this file to discover all available pages before exploring further. # MCP tools and what they cost > Every tool the Generect MCP server exposes, whether it spends credits, and the order to call them in The MCP server is a thin, honest wrapper over the Generect API. Two rules make it safe to hand to an autonomous agent: 1. **Sizing an audience is free.** You can learn how many people match an ICP, and what pulling them would cost, without spending anything. 2. **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](https://app.generect.com/settings/billing), and `get_balance` returns them too. See [Pricing](/billing/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](/api-reference/database-vs-realtime). 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 ```text theme={null} 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](/api-reference/introduction) 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 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.