RecruitMCP

Changelog

2026-10-13

Cursor's mcp.json header is Bearer ${env:RECRUITMCP_KEY}. Claude Code's .mcp.json uses ${RECRUITMCP_KEY}. Claude Desktop's mcp-remote header is Authorization:${AUTH_HEADER} with AUTH_HEADER set to Bearer <key>.

Signup accepts an optional first name and a first-party attribution object, or the rmcp_attr cookie from the first visit. 401, 402, 403, 404, 406, 422, 429, and 503 include error.fix and error.docs.

The TypeScript and Python clients read RECRUITMCP_KEY. RECRUITMCP_API_KEY is still accepted as a fallback.

The MCP protected-resource URL is the host the client called, or MCP_PUBLIC_URL when that is set. tools/list returns only tools the key or token can run. lookup_people is the deprecated enrich alias. HTTP MCP needs Accept: application/json, text/event-stream.

Every authenticated mutation accepts Idempotency-Key. Paid and sending calls still require it unless dry_run=true. Other POST, PUT, PATCH, and DELETE calls replay when a key is sent and run when it is omitted. A second call with the same key waits for the first and replays its response. A different body is 409 idempotency_key_reused. A key longer than 128 characters is 400. A dry_run response has its own schema. Search text is at most 1,000 characters. JSON body integers must be numbers; query parameters still accept numeric strings. An invalid cursor is Invalid cursor. A lookup with no letter returns an empty result. The checkout success page title is Payment received. Matching the checkout session to a workspace waits on Stripe for at most 8 seconds; a longer return is Stripe, not the workspace lookup.

Opening the checkout success page without a console key names the workspace and emails a sign-in link to the account email. It does not show the signup form. A Stripe purchase that had no credits.purchased event gets one.

Lists, enrollments, exports, and opt-outs keep one person when the same profile is sent as both member ids. The error guide names contacts_unavailable, gateway_timeout, free_tier_limit, account_required, and confirm_token_used. total_elements is an estimate from before the location filter. GET /v1/billing/transactions accepts kind, and a returned profile enrich says the credits were returned. POST /v1/seen refuses a profile id that is not a member id.

The key created at signup includes outreach:approve together with outreach:send. A key created later still omits outreach:approve unless the request lists it.

A search or company lookup that does not finish in time returns 504 gateway_timeout and charges nothing. Profiles already in hand come back with next_cursor, and only those are charged. Retrying does not charge a profile this workspace already paid for.

profile_id stays the search id. alternate_id is the other member id for the same person. Seen, opt-out, suppression, enrollment, and the profile cache accept either id.

A requested location drops profiles outside that place, and those are not charged. Several locations are interleaved. A CXO-only search (seniority_level_ids 310) drops titles that are not chief, founder, or C-level.

GET /v1/billing/transactions lists grants, purchases, usage, and expiries. credits.granted, credits.purchased, and credits.used are events. GET /v1/events accepts type as well as types. Checkout returns to /console?checkout=success&session_id=…, and the console confirms the payment. The spec is at /openapi.json.

14 October 2026: Scale is €399 a month for 100,000 credits. A workspace that has never paid is 402 free_tier_limit after 60 search pages in total, or 40 location lookups per UTC day.

photo is a URL on this API, https://recruitmcp.com/v1/media/{token}. The token does not contain the original address. It expires after 7 days, and each API response signs a new one. The image response is cached privately for one day. Erasure and a confirmed opt-out delete the cached photo, and every token for that person then returns 404. CSV exports use the same kind of URL.

Contact lookup returns 503 contacts_unavailable when it is switched off. The call looks nothing up and charges nothing, including dry_run. GET /health reports that check as { "ok": true, "mode": "unavailable", "reason": "not_enabled" }. A component switched off on purpose does not fail the overall report. A missing contact provider still does.

A people search that filters on current job title puts a closer title match ahead of a weaker one in the page already fetched. That reorder does not buy another page.

A reused confirm_token is 409 confirm_token_used. Ask for a new preview to get another token. Replaying the same Idempotency-Key still returns the first response.

POST /v1/people:enrich answers 202 while a profile job is queued, and X-Credits-Charged on that response is 0. The charge happens when the job completes.

A workspace that has never paid can buy 60 search pages in total and 40 location lookups per UTC day. Past that, the call is 402 free_tier_limit with details.kind of search_pages or geo_lookups. Cached pages do not count, and signup credits do not lift the cap. A paid plan removes it. A page of search results is cached for 24 hours, so repeating the same search does not buy that page again.

Search, profile, company, and contact calls run when the key is authorized. confirm is still accepted on those calls and does not change them. dry_run=true is still a free preview with no side effects. A key may set approval_threshold_credits. Unset means no threshold on HTTP and 500 credits on MCP. Above that threshold the response is 409 approval_required with an estimate and a confirm_token, and the call does not charge. Outreach sends still need outreach:send and an explicit confirm. Erasure and suppression still need privacy:write. The version date is unchanged. Clients that already send confirm, an Idempotency-Key, or dry_run keep working.

The first public version. A short balance returns the profiles it could pay for and next_cursor for the rest. Leads already billed are free. credits.low uses each workspace's low_balance_credits (default 250). Pin it with RecruitMCP-Version: 2026-10-13; keys pin it when they are created. See Errors, pagination, and versions for what counts as a breaking change.

API shape

  • Three layers: Raw (filters one to one with the person index, full profiles), Building blocks (lookups, seen register, lists, suppressions), and Guided (intents, search plans, runs). See API layers.
  • Every operation has an operationId. openapi.yaml is the source of the API reference and of the generated TypeScript and Python SDKs and the n8n node.
  • Every list uses cursor pagination: { object: "list", data, next_cursor, has_more }.
  • Every paid or sending call takes ?dry_run=true and needs an Idempotency-Key to execute.
  • Distinct error codes for every failure the client should handle differently, including unsupported_filter, not_cached, daily_credit_cap_reached, outreach_cap_reached, account_paused, and account_not_ready.

Sourcing

  • POST /v1/people/search returns the profiles you asked for. limit is how many to return. cursor continues. A dry run returns the estimate for free, and credits_max equals limit.
  • Intents use must, nice, and exclude blocks. Every intent, plan, and raw search reports applied_filters and ignored_fields.
  • Raw filters include past companies, schools, job functions, profile languages, company headcount, and names. Filters the index cannot apply, such as time in the current title, are refused with unsupported_filter. Raw-layer requests also refuse unknown fields and raw: true; profiles are always normalized.
  • GET /v1/people/{profile_id} never charges. POST /v1/people:enrich takes up to 100 ids or URLs and returns the full profile without email or phone. POST /v1/people:fetch is a deprecated alias. POST /v1/people:match finds one person by name and company.
  • Full CRUD for intents, the seen register (with tags and external ids), and lists (with CSV export).
  • There is no fit score. Candidates carry distance, experience, tenure, and tier.

Platform

  • Account-wide events and signed webhook endpoints for runs, jobs, contacts, enrollments, actions, replies, accounts, and credits.
  • Customers: sub-workspaces with their own memory, outreach accounts, and daily caps, selected by header or by a bound key.
  • OAuth 2.1 for MCP clients such as claude.ai, next to API keys. Sending outreach is its own scope, outreach:send.
  • MCP toolsets selected on the URL, a one-call start_search, get_search_results that waits, output schemas, prompts, resource templates, and get_guide.

Outreach

  • Enroll a run, a list, profile ids, or named people in one call, with a full preview first.
  • Sequences, enrollments, actions, and conversations have full read and manage endpoints.
  • The safety layer is unchanged: caps, warmup, daily jitter, spacing, working hours, reply-stop, and auto-pause. Raising a cap above its default needs account:manage and risk_acknowledged, and is audited. outreach:write can only lower a cap.
  • Approving or rejecting a held message needs outreach:approve. A new key omits that scope unless the request lists it. Keys that already had outreach:send keep it. A held message expires after 7 days: the action outcome becomes expired and the enrollment pauses, so later steps do not send until it is resumed. Rejecting a step skips that step. Later steps still run.
  • The daily new-outreach cap counts per account. A workspace lowered limit on that cap applies to every account. It is not a shared pool. Working hours use the workspace timezone, default Europe/Brussels, Monday to Friday 08:00–19:00. The account IP pins the connection country and does not change the window.
  • An enrollment above approval_threshold_enrollments returns 409 approval_required with the preview and confirm_token. Unset means no threshold on HTTP and 25 scheduled enrollments on MCP. A recruiter seat without a public client IP is 428 client_ip_required.

Credits and privacy

  • Credits live in buckets with a source and an expiry. Unused plan credits roll over for 2 more cycles, top-ups expire after 12 months, and free signup credits after 30 days.
  • A person can opt out at /opt-out. Suppression applies in every layer, raw search included.
  • POST /v1/erasures erases one person from the workspace and keeps a hashed suppression.

Prices on this page are the defaults: 1 credit per lead returned, 2 per live profile, 1 when a company is found live. A lookup with no result is free, 1,250 credits on signup, €49 per connected account per month.