# 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, 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: either an API token header (`Authorization: Bearer
  <YOUR_VAYNE_API_TOKEN>`) or **OAuth** — clients that support the MCP OAuth
  flow (e.g. claude.ai custom connectors) can simply add the Server URL and
  will be redirected to Vayne to sign in and authorize.

Get or rotate your API token in the Vayne app under **API Settings**, and
copy-paste client configuration (Claude Desktop, Claude Code, Cursor, Agent
SDK) from the **MCP Setup** modal.

A human-readable version of this guide with per-client setup snippets 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.

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

**Contact finder (email/phone enrichment)** — `create_contact_finder`,
`get_contact_finder`, `list_contact_finders`. One contact per call.

**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** — the API token is wrong or was rotated; copy a
  fresh one from the Vayne app.
- **New tools or schema changes don't show up** — MCP clients cache the tool
  list at connect time; fully disconnect/reconnect the client.