Generect MCP

Generect API MCP Server

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.

Get Your API Key

Sign up and get your API key at https://app.generect.com

Remote MCP Server (OAuth - Recommended)

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:

{
  "mcpServers": {
    "generect": {
      "url": "https://mcp.generect.com/mcp",
      "type": "http"
    }
  }
}

When you first connect, the client will initiate an OAuth flow:

1. You'll be redirected to the authorization page
2. Enter your Generect API token from app.generect.com
3. Authorize the client to access your API
4. The client receives an access token and can now use the MCP tools

OAuth Endpoints

Direct API key (no OAuth)

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:

Authorization: YOUR_API_KEY
Authorization: Bearer YOUR_API_KEY
Authorization: Token YOUR_API_KEY
Authorization: Bearer Token YOUR_API_KEY   (legacy)

Example for mcp-remote:

{
  "mcpServers": {
    "generect": {
      "command": "mcp-remote",
      "args": [
        "https://mcp.generect.com/mcp",
        "--header",
        "Authorization: Bearer YOUR_API_KEY"
      ]
    }
  }
}

Local Installation (Alternative)

For local development or when OAuth is not needed:

1. Requirements: Node >= 18

2. Configure environment:

GENERECT_API_BASE=https://api.generect.com
GENERECT_API_KEY=Token <api-key>
GENERECT_TIMEOUT_MS=300000
JWT_SIGNING_KEY=<your-secret-key-for-jwt-signing>
TOKEN_ENCRYPTION_KEY=<32-byte-hex-key-for-token-encryption>

3. Local dev (optional)

npm install
npm run dev:http

4. Build and start (stdio server)

npm run build && npm start

Logging

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:

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:

pm2 logs generect-mcp                                # live
pm2 logs generect-mcp --err                          # errors only
grep tool_call ~/.pm2/logs/generect-mcp-out.log      # only LLM tool inputs

Test mode

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.

{
  "mcpServers": {
    "generect": {
      "command": "mcp-remote",
      "args": ["https://mcp.generect.com/mcp", "--header", "Authorization: Bearer test_YOUR_TEST_KEY"]
    }
  }
}

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.

Tools

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

Billable

database vs realtime

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.
• Counting is the exception — a realtime count costs money, so count_leads / count_companies refuse to run one unless you ask for mode: "realtime" explicitly. They tell you which filters forced the choice instead.

Filter vocabularies — read them, do not guess

Measured against the live API, the v1 search endpoints validate their filters inconsistently:

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:

• an unknown industry, headcount bucket or company type is refused locally with the closest valid names (Fintech → Financial Services, 50-200 → 51-200), and nothing is sent or charged;
• a value that is merely mis-spelled or mis-cased is corrected (software development → Software Development) — matching is exact, so sending it as typed would have returned zero;
• an unknown seniority or function is a warning, not 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 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:

generect://vocabulary/industries        434 names, with parents
generect://vocabulary/seniorities
generect://vocabulary/functions         (realtime only)
generect://vocabulary/company-types
generect://vocabulary/headcounts
generect://vocabulary/follower-ranges   (realtime only)
generect://account/pricing              this account's real per-operation prices
generect://account/balance              balance and month-to-date usage

They are regenerated from the backend's own filter data with node scripts/gen-vocabulary.mjs <api_parser checkout> — never hand-edited.

Prompts