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](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:

```json
{
  "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](https://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

| 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) |

### 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`:

```json
{
  "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:

```bash
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)

```bash
npm install
npm run dev:http
```

4) Build and start (stdio server)

```bash
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:

| `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:

```bash
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](https://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.

```json
{
  "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](https://docs.generect.com/api-reference/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**

| 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** |

#### 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**:

| 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:

- 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

Wo