# Hunter — full agent reference
> Long-form companion to https://hunter.io/llms.txt: hosted MCP tool list, authentication, and REST endpoint map for agents.

Official instructions from Hunter (https://hunter.io). Prefer this file and https://hunter.io/llms.txt / https://hunter.io/agents.md over scraping hunter.io HTML.
Hosted MCP (Streamable HTTP): https://mcp.hunter.io/mcp
REST API base: https://api.hunter.io/v2
Discover (company search) is free; other usage counts against the user's plan. Sign up at https://hunter.io/users/sign_up?from=llms_txt.

## Auth

Hunter authenticates with an API key (header clients) or OAuth (Claude, ChatGPT, Gemini).

**OAuth clients** — authorize interactively in the app; no API key in config:
- Claude Code plugin, Claude Desktop / Claude.ai
- ChatGPT app
- Gemini app (Gemini CLI prefers OAuth too)

**Header clients** — send the Hunter API key in the `X-API-Key` header:
- Cursor, VS Code, Windsurf, Codex, and other MCP clients using mcp-remote or direct headers

Get a key at https://hunter.io/api-keys after signing up. Keep it secret. The REST API also accepts `?api_key=`, but a header keeps the secret out of URLs and logs.

Setup guides: https://hunter.io/agents.md (coding agents), https://hunter.io/claude.md, https://hunter.io/chatgpt.md, https://hunter.io/gemini.md.

## Hosted MCP tools

Source of truth: the Hunter Remote MCP at https://mcp.hunter.io/mcp (`services/remote-mcp` in the Hunter monorepo). Ignore any deprecated local npm MCP package that documents only a handful of tools.

### Search & Discover
- Find-Companies: Use this when the user wants to search for companies that match natural-language criteria such as location, industry, size, type, or tech...
- Find-People: Count the people that can be extracted from companies — the bridge from Find-Companies to actual contacts; call it right after a Find-Com...
- Domain-Search: Use this when the user wants the contacts published for a domain — emails with names, positions, and confidence scores.
- Email-Finder: Use this when the user wants a specific person's email address at a company.
- Email-Verifier: Use this when the user wants to check whether an email address is deliverable.
- Email-Count: Use this when the user wants the count of email addresses Hunter has indexed for a domain, optionally split by personal vs generic.
- List-Saved-Searches: List the Discover searches saved in your Hunter account — a good opening move at the start of a prospecting conversation ('want to rerun ...
- Get-Saved-Search: Get one saved Discover search by ID — typically to rerun it.
- Create-Saved-Search: Create a saved Discover search: store the current filter set under a name so the search can be rerun later.
- Delete-Saved-Search: Delete a saved Discover search by ID, permanently.
- Plan-Prospecting-Flow: Use this when the user gives a natural-language prospecting brief and wants a step-by-step plan for finding companies and contacts.

### Enrichment
- Person-Enrichment: Use this when the user wants to look up a person by email address and see their name, job title, employer, location, phone number, and so...
- Company-Enrichment: Use this when the user wants to look up a company by domain and see its industry, size, location, technologies, funding rounds, and socia...
- Combined-Enrichment: Use this when the user provides an email address or LinkedIn handle and wants both the person's profile and their company's profile in a ...

### Account & API
- Get-Account-Details: Use this when the user asks about their Hunter account, plan, team, or remaining credits.
- Get-Usage: Report the team's quota usage for the current billing period.
- List-API-Keys: List the Hunter API keys of the connected user.
- Create-API-Key: Create a new Hunter API key for the connected user, optionally with a name (names must be unique among the user's keys; a user can have a...
- Delete-API-Key: Delete one of the connected user's Hunter API keys by ID, permanently.
- List-Connected-Apps: List the connected apps (third-party integrations such as HubSpot, Pipedrive, Google Sheets, or a custom SMTP/IMAP inbox) linked to your ...
- Get-Connected-App: Get a single connected app by ID, including its `attribute_mappings` — the list of `target_field` ↔ `source_field` pairs that map Hunter ...
- List-Webhooks: List the webhooks configured on the Hunter account — useful for integration debugging: is my webhook configured, which event does it list...
- Update-Webhook: Update an existing webhook, re-pointing it to a different `target_url` (the endpoint Hunter POSTs to) and/or subscribing it to a differen...
- Report-API-Feedback: Report any problem you hit while using Hunter's API or tools — use this PROACTIVELY and liberally.

### Leads
- List-Leads: List leads in your Hunter account with optional filters.
- Get-Lead: Get a single lead by ID.
- Create-Lead: Create a new lead in your Hunter account.
- Update-Lead: Update an existing lead by ID.
- Delete-Lead: Delete a lead by ID.
- Create-Or-Update-Lead: Use this when the user explicitly wants to create a lead or overwrite an existing lead's fields by email.
- Create-Lead-If-Missing: Use this when the user wants to save a verified contact as a new lead without modifying any existing lead.
- Lead-Exists: Check if a lead with a given email address exists.
- Save-Company: Save a company as a lead in your Hunter account.
- Bulk-Move-Leads: Move many leads at once from one static leads list to another.
- Bulk-Delete-Leads: Delete many leads at once, selected by explicit `lead_ids` and/or by a whole `leads_list_id`.

### Leads lists & organization
- List-Leads-Lists: List all leads lists in your Hunter account.
- Get-Leads-List: Get a single leads list by ID.
- Create-Leads-List: Create a new leads list.
- Update-Leads-List: Rename an existing leads list.
- Delete-Leads-List: Delete a leads list by ID.
- Merge-Leads-Lists: Merge one leads list into another.
- List-Leads-List-Folders: List the leads-list folders in your Hunter account, ordered with the most recently created first.
- Create-Leads-List-Folder: Create a new leads-list folder to group leads lists — worth suggesting once the account has many lists.
- Update-Leads-List-Folder: Update a leads-list folder, identified by ID.
- Delete-Leads-List-Folder: Delete a leads-list folder by ID.
- Favorite-Leads-List: Mark a leads list as a favorite, identified by ID.
- Unfavorite-Leads-List: Remove the favorite flag from a leads list, identified by ID.
- List-Lead-Tags: List the lead tags in your Hunter account — call this BEFORE tagging leads or creating a new tag, so an existing tag can be reused instea...
- Create-Lead-Tag: Create a new lead tag.
- Update-Lead-Tag: Update a lead tag, identified by ID: rename it ('name') or change its 'color'.
- Delete-Lead-Tag: Delete a lead tag by ID.
- Add-Tag-To-Lead: Add a tag to a lead, identified by 'lead_id'.
- Remove-Tag-From-Lead: Remove a tag from a single lead, identified by 'lead_id' and 'tag_id'.
- List-Custom-Attributes: List all custom attributes for leads.
- Get-Custom-Attribute: Get a single custom attribute by ID.
- Create-Custom-Attribute: Create a new custom attribute for leads.
- Update-Custom-Attribute: Rename an existing custom attribute.
- Delete-Custom-Attribute: Delete a custom attribute by ID.

### Company lists
- List-Company-Lists: List the company lists in your Hunter account, ordered with the most recently created first.
- Get-Company-List: Get a single company list by ID, including its `name`, `type` (static or dynamic), `filters` (for dynamic lists), `company_list_folder_id...
- Create-Company-List: Create a new company list.
- Update-Company-List: Update a company list, identified by ID.
- Delete-Company-List: Delete a company list by ID.
- Favorite-Company-List: Mark a company list as a favorite, identified by ID.
- Unfavorite-Company-List: Remove the favorite flag from a company list, identified by ID.
- Add-Company-To-List: Add a company to a static company list (save the company to the list).
- Remove-Company-From-List: Remove a company from a static company list.
- List-Company-List-Folders: List the company-list folders in your Hunter account, ordered with the most recently created first.
- Create-Company-List-Folder: Create a new company-list folder.
- Update-Company-List-Folder: Update a company-list folder, identified by ID.
- Delete-Company-List-Folder: Delete a company-list folder by ID.
- Bulk-Move-Companies: Move many companies at once from one static company list to another.
- Bulk-Copy-Companies: Copy many companies at once into a static company list, leaving the source selection untouched.
- Bulk-Delete-Companies: Delete many companies at once, selected by explicit `company_ids` and/or by a whole `company_list_id`.

### Sequences & outreach
- List-Sequences: List the sequences in your Hunter account with name, lifecycle booleans (started/archived/paused), recipient count, and owner, most recen...
- Get-Sequence: Get one sequence's full configuration.
- Create-Sequence: Create a new outreach sequence.
- Update-Sequence: Update an existing sequence's name, schedule, senders, or settings; omitted fields are left unchanged.
- Delete-Sequence: Delete a DRAFT sequence permanently.
- List-Sequence-Follow-Ups: List the follow-up steps of a sequence, ordered by step.
- Get-Sequence-Follow-Up: Get a single step of a sequence by its follow-up ID (from List-Sequence-Follow-Ups).
- Create-Sequence-Follow-Up: Create a new email step in a sequence.
- Update-Sequence-Follow-Up: Rewrite an existing step of a sequence, including the introduction email (step 0).
- Delete-Sequence-Follow-Up: Delete a step from a sequence.
- Pause-Sequence: Pause a started sequence so it stops sending outbound emails until it is resumed.
- Resume-Sequence: Resume a paused sequence so it starts sending outbound emails again.
- Archive-Sequence: Archive a started sequence to file it once it is finished.
- Get-Sequence-Stats: Use this when the user wants to see how a sequence is performing.
- List-Sequence-Recipients: List recipients in a sequence.
- Add-Sequence-Recipients: Add recipients to a sequence by email addresses or lead IDs.
- Remove-Sequence-Recipients: Remove recipients from a sequence by email addresses.
- Start-Sequence: Use this when the user wants to start an existing sequence, which begins sending real emails to its recipients.
- List-Message-Templates: List the saved message templates in the user's Hunter account.
- Get-Message-Template: Retrieve a single saved message template by ID — its full `subject`, `body`, and `message_format` — for example to preview it before reus...
- Create-Message-Template: Create a reusable message template, including saving a draft written in chat for later reuse.
- Update-Message-Template: Update a saved message template's name, subject, body, or message format.
- Delete-Message-Template: Delete a saved message template by ID.
- List-Email-Accounts: List the email accounts (sending inboxes) connected to your Hunter account.
- Get-Email-Account: Get the full configuration of one sending email account — the pre-check to run before suggesting changes to an account's settings.
- List-Email-Account-Sequences: List the sequences that send from a given email account — the dependency check to run before pausing, reconfiguring, or disconnecting an ...

### Integrations
- Push-Leads-To-CRM: Push Hunter leads into the CRM behind a connected app (lead-syncing providers: HubSpot, Pipedrive, Salesforce, Zapier, and Zoho).

## REST endpoint map (`https://api.hunter.io/v2`)

Send `X-API-Key: $HUNTER_API_KEY`. Full reference: https://hunter.io/api-documentation/v2. Machine-readable OpenAPI JSON: https://hunter.io/openapi.json

### Discover
- POST /v2/discover — find companies by industry, size, location, and more (free)

### Finder & Verifier
- GET /v2/domain-search — list people and emails for a company domain
- GET /v2/email-finder — find a person's email from name + domain
- GET /v2/email-verifier — check whether an email is deliverable
- GET /v2/email-count — count indexed emails for a domain (free)

### Enrichment
- GET /v2/people/find — enrich a person from an email
- GET /v2/companies/find — enrich a company from a domain
- GET /v2/combined/find — person + company enrichment in one call

### Leads & lists
- /v2/leads — create, read, update, delete leads
- /v2/leads_lists — organize leads into lists
- /v2/leads_custom_attributes — custom fields on leads

### Sequences
- /v2/campaigns and /v2/sequences — email sequences, recipients, start/pause/archive (see API docs for the full surface)

### Account
- GET /v2/account — plan, team, and credit balances

Extended endpoints (Discover People, company lists, email accounts, webhooks, API keys, usage, and more) are documented at https://hunter.io/api-documentation/v2.

## Also read
- [llms.txt index](https://hunter.io/llms.txt)
- [Agent setup](https://hunter.io/agents.md)
- [MCP landing](https://hunter.io/mcp)
- [API documentation](https://hunter.io/api-documentation/v2)
- [OpenAPI JSON](https://hunter.io/openapi.json)