The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Generect MCP listing page.
B2B lead and company data for AI agents — search, preview, enrich, email and phone lookup over the Generect API.
Built so an agent can work without burning a customer's balance: sizing an audience is free, every tool says up front whether it costs money, and every response reports what was actually charged.
Sign up and get your API key at https://app.generect.com
This MCP server implements OAuth 2.1 authorization as specified by the Model Context Protocol.
Use our hosted MCP server with any OAuth-compliant MCP client:
When you first connect, the client will initiate an OAuth flow:
| Endpoint | Description |
|---|---|
/.well-known/oauth-protected-resource | Protected Resource Metadata (RFC 9728) |
/.well-known/oauth-authorization-server | Authorization Server Metadata (RFC 8414) |
/.well-known/jwks.json | JSON Web Key Set for token verification |
/oauth/authorize | Authorization endpoint (login + consent) |
/oauth/token | Token endpoint |
/oauth/register | Dynamic Client Registration (RFC 7591) |
If your MCP client cannot complete the OAuth flow, you can pass the API key directly via the Authorization header. The server accepts any of:
Example for mcp-remote:
For local development or when OAuth is not needed:
Requirements: Node >= 18
Configure environment:
The server emits one structured JSON log line per event to stderr (stdout is reserved for the MCP stdio protocol). Metadata logging is on by default; set MCP_LOG=0 to disable it entirely.
Privacy — payloads are redacted by default. Request/response payloads can contain personal data of prospects (names, company domains, generated emails). By default these values are not logged verbatim: each is reduced to a non-identifying shape marker (e.g. "first_name": "<str:4>"), so you can see which fields were sent without recording the data itself. Set MCP_LOG_PAYLOADS=1 to log payloads verbatim — intended for short-lived debugging, with the data owner's consent.
Events:
event | When | Key fields |
|---|---|---|
tool_call | LLM invokes a tool | reqId, tool, input (redacted unless MCP_LOG_PAYLOADS=1) |
api_request | Outbound call to Generect API | url, method, body (redacted unless MCP_LOG_PAYLOADS=1; never the token) |
api_response | Generect API responded | url, status, ms |
tool_result | Result returned to the LLM | reqId, tool, ms, output (redacted unless MCP_LOG_PAYLOADS=1) |
tool_error / api_error | Failure | reqId/url, error, ms |
reqId correlates a tool_call with its tool_result. Set MCP_DEBUG=1 for additional verbose output.
The hosted server runs under PM2 (not Docker). View logs on the host with:
Generect's API picks live or test mode from the key, not the URL — so this
server needs no separate deployment and no extra tool. Paste a test key
(test_…, created at
app.generect.com/settings/api) into
the same config and every tool answers with fictional data, at the speed the
real endpoint runs, showing the price the real call would have cost, charging
nothing.
Every result from a test key carries test_mode: true and a notice telling the
model the people are fictional. That is not decoration. An agent handed twelve
invented prospects with no marker will summarise them as twelve prospects, and
the person reading the summary has no way to tell — the likeliest failure of
test mode in an agent channel is a confident report about people who do not
exist. The marker is added centrally, so no tool can forget it.
See Test mode for the magic inputs that force a 402, a 429 or a timeout on demand.
Every tool states in its own description whether it is free or billable, and every
response carries a cost block with the amount the API actually charged. Tools
accept timeout_ms.
Free — start here
| Tool | What it does |
|---|---|
count_leads | How many leads match an ICP + what the next step costs at your rates. Run before search_leads. |
count_companies | Same, for companies. |
get_balance | Balance, this account's real per-operation prices, plus optional include_usage (spend by operation) and include_token_analytics (which token made which calls). |
get_bulk_job | Poll a bulk job (the work was billed at submit time). |
manage_webhooks | List/create/update/delete/test webhook endpoints. |
health | Liveness + credential check against a free endpoint. Safe for monitors. |
Billable
| Tool | Billed |
|---|---|
search_leads | per returned row |
search_companies | per returned row |
preview_leads | per returned row (cheapest way to see real people); count_only: true is free and is a second opinion on count_leads, since preview and cached search are different indexes |
enrich_lead / get_lead_by_url | per record found |
resolve_profile | per resolved profile — the cheapest call here; an unresolvable reference is free |
enrich_company | per record found |
generate_email | per valid email found |
validate_email | per email submitted — every address, whatever the verdict |
find_phone | per phone found — the most expensive operation here |
start_bulk_job | per record, reserved at submit time |
Every search/enrich runs against either the cached database (sub-second, cheaper,
free counts) or a live LinkedIn lookup (5–60s, pricier, billable counts, every
filter). Tools take mode: "auto" | "database" | "realtime":
auto (default) tries the cheap path and escalates only if the API says a
filter you passed does not exist there. The escalation is reported in the
response, never silent.database never escalates: if a filter is unsupported you get an error, not a
bigger bill.count_leads /
count_companies refuse to run one unless you ask for mode: "realtime"
explicitly. They tell you which filters forced the choice instead.Measured against the live API, the v1 search endpoints validate their filters inconsistently:
| Filter | Unknown value |
|---|---|
locations, company_headcounts, company_types | HTTP 400 naming the field |
company_industries, seniorities | accepted — 0 results, $0, no error |
That second row is the dangerous one. company_industries: ["Fintech"] is not a
LinkedIn industry and comes back as a perfectly successful count of zero, which
reads exactly like "this audience does not exist".
So the server checks these values itself, before sending anything:
Fintech → Financial Services,
50-200 → 51-200), and nothing is sent or charged;software development → Software Development) — matching is exact, so
sending it as typed would have returned zero;Owner finds people even though the canonical label is
Owner / Partner);allow_unlisted_values: true overrides the check if this server's snapshot is
ever behind the API.The full vocabularies are exposed as resources, so a client can read them once and stop guessing:
They are regenerated from the backend's own filter data with
node scripts/gen-vocabulary.mjs <api_parser checkout> — never hand-edited.
Workflow prompts ship with the server and appear as slash commands in clients
that support them: size_an_audience, build_prospect_list, enrich_my_list,
spend_report. Each one starts from the free step.
A row cap bounds results, not money. Any call whose worst case exceeds
MCP_MAX_SPEND_PER_CALL (default $5) 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 undone.
get_balance before and after a batch gives you an exact spend figure to report.
Tools give an agent the ability to call Generect; a skill gives it the procedure.
skills/generect-lead-workflows documents the flows above so an autonomous agent
follows them without being told each time:
See skills/README.md. Release process and the full list of places a version has to land: RELEASING.md.
Add to ~/.claude/claude_desktop_config.json (or via UI → MCP Servers). Recommended: run via npx so users don't install anything globally.
macOS note: If Claude shows "spawn npx ENOENT" or launches an older Node via nvm, set command to the absolute npx path and/or override PATH:
Alternative without npx:
Then use:
The hosted server (https://mcp.generect.com) runs under PM2 as mcp_user on
the host, fronted by nginx (TLS), defined by ecosystem.config.cjs.
Deploys are automatic. A green ci run on main triggers
deploy-prod.yml, which reaches the host over
SSH with a key that can run exactly one thing —
deploy/remote-deploy.sh — and verifies the public
endpoint afterwards. The script:
main (never an older commit);reload, not --update-env);deploy/sandbox-test.sh exercises all of that against a throwaway copy of the
repo with its own pm2 — run it after touching the deploy script. One-time host
setup is deploy/bootstrap-chronos.sh (as root).
Single instance only. OAuth state (registered clients, auth codes) and MCP sessions are held in memory, so the server must run as one instance. Scaling horizontally requires a shared store (e.g. Redis) first — see ecosystem.config.js.
Required secrets (fail-closed). In production (NODE_ENV=production) the server refuses to start unless JWT_SIGNING_KEY is set to a strong, non-default value; it never falls back to a hardcoded default or an ephemeral key. TOKEN_ENCRYPTION_KEY, if set, must be exactly 64 hex characters (32 bytes).
Docker is supported for local/alternative runs. Build locally:
Run the server in a container (note: the same production secrets are required — an insecure default will cause the container to exit at startup):
Some MCP clients allow spawning the server via SSH, using stdio over the SSH session. Example config:
All three default to free API calls only — a smoke test should never quietly bill whoever runs it.
--paid adds one
3-row search and one email lookup, and the run prints what it spent:TOKEN_ENCRYPTION_KEY (or derived from JWT_SIGNING_KEY)JWT_SIGNING_KEY, and never publishes symmetric key material in the JWKSACCESS_TOKEN_TTL_SECONDS) and are renewed via a refresh_token grant; refresh tokens are rotated on use and revocable at POST /oauth/revoke (RFC 7009). Tokens issued before this change remain valid (no forced re-auth)MCP_REGISTER_RATE_MAX, default 60/hour) and the client store is capped (MCP_MAX_CLIENTS, default 5000, LRU eviction that never drops an in-use client)MCP_REDIRECT_POLICY=open). Accepted: any https URL, http only on loopback/private addresses, and an app's own private-use URI scheme (cursor://…, vscode://…, com.example.app:/cb — RFC 8252 §7.1). Refused regardless of policy: cleartext http to a public host, #fragments, embedded credentials, over-long URIs, and browser-executable schemes (javascript:, data:, file:, …) — that URI is navigated to from our own origin, so those would be XSS. Loopback callbacks match on everything but the port (RFC 8252 §7.3), since a native app's listener gets an ephemeral one. Set MCP_REDIRECT_POLICY=strict to fall back to the first-party allowlist (*.generect.com, claude.ai, linear.app, plus MCP_ALLOWED_REDIRECT_DOMAINS / MCP_ALLOWED_REDIRECT_SCHEMES)MCP_ENABLE_CIMD, default on) fetches only https URLs that resolve exclusively to public IPs, with no redirect following, a hard timeout, and a response-size cap (blocks loopback / RFC1918 / link-local / cloud-metadata targets)| Var | Default | Effect |
|---|---|---|
ACCESS_TOKEN_TTL_SECONDS | 2592000 (30d) | Access-token lifetime |
REFRESH_TOKEN_TTL_SECONDS | 7776000 (90d) | Refresh-token lifetime |
MCP_MAX_CLIENTS | 5000 | Cap on the in-memory DCR client store |
MCP_REGISTER_RATE_MAX | 60 | Max /oauth/register calls per IP per window |
MCP_REGISTER_RATE_WINDOW_MS | 3600000 (1h) | Rate-limit window |
MCP_ENABLE_CIMD | true | Allow client-id-as-metadata-URL (SSRF-guarded) |
MCP_REDIRECT_POLICY | open | open = any client may register its callback; strict = first-party allowlist only |
MCP_ALLOWED_REDIRECT_DOMAINS | — | Extra allowed redirect hostnames, strict only (comma-separated) |
MCP_ALLOWED_REDIRECT_SCHEMES | — | Extra allowed private-use URI schemes, strict only (comma-separated, e.g. cursor,vscode) |
MCP_ALLOW_ANY_HTTPS_REDIRECT | — | Legacy: opens https callbacks under strict (implied by open) |
MCP_LOG_PAYLOADS=1 to opt in)/oauth/authorize does not ask for a password. It hands off to a page in the
product where the user is already signed in, and that page posts a freshly
minted API token back to /oauth/broker. Two env vars decide which page that is,
and they must be changed together:
| Var | Effect |
|---|---|
MCP_CONSENT_URL | Where /oauth/authorize redirects the user (…/authorize/mcp?handoff=…&mcp=…) |
MCP_CONSENT_ORIGIN | The only Origin allowed to call /oauth/broker. Defaults to the origin of MCP_CONSENT_URL — but production sets it explicitly in .env, so the default does not save you |
Moving consent from one host to the other by editing only MCP_CONSENT_URL
leaves the broker refusing the new page with
403 {"error":"forbidden","error_description":"Origin not allowed to broker consent."},
after the user has already clicked Approve. Change both lines, then prove it:
CORS is not the control here — the server reflects any Origin (bearer auth,
no cookies), so a working preflight proves nothing about the broker.
mcp.generect.com runs pm2, not Docker (.github/workflows/deploy-prod.yml
is the unused Docker path). Single instance, always: OAuth state and MCP sessions
live in memory, so a second worker split-brains auth.
Then verify from outside the box — pm2 list showing online is not evidence
that the new behaviour is live: