# Vayne MCP — Agent Guide

Vayne is a LinkedIn data platform: Sales Navigator scraping, profile/company
scraping, job scraping and search, post-engagement scraping, reverse email
lookups, company social lookups from a website, and contact enrichment. This page is written to be handed to an AI
agent (or read by a human) to use Vayne through MCP.

## Connecting

- Transport: **Streamable HTTP**
- Server URL: `https://mcp.vayne.io/mcp`
- Auth: **OAuth** (default) or an API token header.

**OAuth** — any client that speaks the MCP OAuth flow (Claude Desktop,
Claude.ai, Claude Code, Cursor, …) only needs the Server URL. In the Claude
apps: **Settings → Connectors → Add custom connector**, paste the Server URL,
click Connect, and authorize Vayne in the browser window that opens. Nothing
to install, no token to copy, and access is revocable from the Vayne account
at any time. Custom connectors require a paid Claude plan.

**API token** — clients that can send custom headers (Claude Code, Cursor, the
Agent SDK, and anything server-side) can use
`Authorization: Bearer <YOUR_VAYNE_API_TOKEN>` instead. Get or rotate the token
in the Vayne app under **API Settings**.

Copy-paste client configuration lives in the **MCP Setup** modal in the app.

A human-readable version of this guide with per-client setup steps lives
at https://www.vayne.io/en/mcp-documentation (FR:
https://www.vayne.io/fr/mcp-documentation), and the product overview at
https://www.vayne.io/en/mcp-server.

## Tools

**Sales Navigator** — `build_search_url` (people), `build_account_search_url`
(companies), `estimate_search`, `create_order`, `list_orders`, `get_order`.
`create_order` is guarded by a credit check and an account-safety throttle
(max 5 orders / 15 min per user), and a single search scrapes at most
20,000 results — larger targets get split into several searches.
People filters cover current and past title/company, profile language
(fixed include-only list), and "connection of" — one person, identified by
their LinkedIn member id (`ACwAA...`); LinkedIn caps connection-of searches
at 1,000 results.

Company filters take **LinkedIn company IDs**, never names. The agent picks
the route by what the user has, and explains the trade-offs first:

1. **IDs already** — passed straight to `build_search_url`.
2. **LinkedIn company URLs** — `scrape_linkedin_url`; the company result's
   `id` is the ID. Exact, 8 credits per company page found.
3. **Names only** — `search_companies`, free for now: `query` for one name,
   or `names` for up to 50 in one call (`POST /api/companies/batch`, which
   runs the searches 10 at a time and can take over a minute). Slower and
   error-prone, since matching on the name can return a homonym, a subsidiary
   or another country's page. Each candidate comes with its LinkedIn page so
   the user can confirm the choice before the search is built.

Every name search is recorded in the Harvest API call register (endpoint
`company-search`, feature `company_search`, no credits).

**LinkedIn URL scraping** — `scrape_linkedin_url` (single URL is sync, 2+ is
an async batch), `get_linkedin_scraping`. Jobs follow the same pattern:
`scrape_linkedin_job`, `get_linkedin_job_scraping`.

**LinkedIn job search** — `search_linkedin_jobs`, `get_linkedin_job_search`,
`load_more_linkedin_job_search` (each extra page costs 1 credit).

**Post scrapers** — `scrape_post_engagement` (one post),
`scrape_profile_posts` (all recent posts of a profile),
`scrape_company_posts` (all recent posts of a company page),
`estimate_profile_posts` / `estimate_company_posts` (pre-flight cost),
`list_post_scrapers`, `get_post_scraper`.

**Reverse lookups (email → LinkedIn URL)** — `create_reverse_lookup`,
`list_reverse_lookups`, `get_reverse_lookup`.

**Company lookups (website → company socials)** — `find_company_socials`
(one website is sync, 2+ is an async batch), `list_company_lookups`,
`get_company_lookup`. Two modes, set by `linkedinOnly`:

- **`true` (default)** — returns only the LinkedIn company URL. 20 credits per
  page found; websites with no LinkedIn page are free up to an allowance per
  billing cycle, then 5 credits each.
- **`false`** — returns LinkedIn, Instagram, YouTube, Facebook, X and Threads,
  in that order, but is charged 20 credits whenever **any** network is found.

Duplicate domains in a batch are merged and charged once, and a batch takes at
most 1000 websites. A single sync call can take up to 20 seconds, which is
normal for this lookup.

**Contact finder (email/phone enrichment)** — `create_contact_finder`,
`get_contact_finder`, `list_contact_finders`. One contact per call. Inputs
depend on `enrichmentType`: `email_only` needs first name, last name and
company domain (LinkedIn URL optional); `phone_only` needs the LinkedIn URL;
`both` needs all four. The server maps the legacy `email_and_phone` value to
the API's `both` and rejects incomplete inputs before calling the API.

**Find people** — `find_people`, `get_find_people`. Quick "people at X who
are Y" search; may be unavailable on some accounts.

**Account state & helpers** — `get_credits`, `check_linkedin_status`,
`search_industries`, `search_locations`, `search_companies`.

## Credits

Two separate pools, both visible via `get_credits`:

- **Scraping credits** fund Sales Navigator orders, reverse lookups, URL/job
  scrapings, job searches (including `load_more`), and post scrapers. Daily
  limits (`daily_limit_leads`, `daily_limit_accounts`) apply ONLY to Sales
  Navigator scrapes.
- **Enrichment credits** fund `create_contact_finder` only.

The assistant should always estimate result counts and confirm credit cost
with the user before creating an order.

## Webhooks

Most `create_*` tools accept an optional HTTPS `webhookUrl` that receives the
results when the job finishes (useful for CRMs, Zapier, n8n, custom
backends). **Trust on first use**: Vayne only delivers to webhook hosts you
have already approved. The first time a job targets a new host, the job runs
normally but the delivery is held and you receive a one-click approval email;
once approved, the host is trusted for all future deliveries. Held deliveries
expire after 7 days if never approved.

## Reading the export

A few CSV columns are not self-explanatory:

- **`recent duplicate`** — `true` means you already scraped this profile in
  the last 90 days.
- **`matching filters`** — `false` means Sales Navigator returned a profile
  that does not exactly match the filters set when building the search.
- **`mismatched filters`** — when `matching filters` is `false`, lists which
  filters did not match (job title, location, company size, industry). For
  profiles with multiple active experiences up to four are checked.
- **`phone` / `email`** — the personal phone/email the prospect themselves
  made public on their LinkedIn profile. Present in only ~1–5% of rows
  depending on the target; this is not an error, the data simply isn't
  there. For more coverage, use Vayne's phone/email enrichment (multi-vendor
  waterfall, paid with enrichment credits). The vendor mix is proprietary
  and changes over time.

## Saved searches (create_order option)

`create_order` can also save the URL as a Saved Search inside Sales
Navigator (`savedSearch: true`). Three caveats: leads only (not accounts),
creation runs on a ~30-minute schedule so it can take up to 30 min to
appear, and LinkedIn caps Saved Searches at 50 per account (creation fails
silently at the cap).

## Troubleshooting

- **"LinkedIn authentication is invalid or expired"** — the LinkedIn cookie
  needs refreshing in the Vayne app (LinkedIn connection settings).
- **A tool returns 401** — on a token connection, the API token is wrong or
  was rotated; copy a fresh one from the Vayne app. On an OAuth connector,
  remove the connector and add it again to re-authorize.
- **New tools or schema changes don't show up** — MCP clients cache the tool
  list at connect time; fully disconnect/reconnect the client.