# Hunter agent setup These are official instructions from Hunter (https://hunter.io) to connect Hunter to your AI agent. Once connected, you can find and verify professional email addresses, list any company's contacts from its domain, discover companies that match a profile, enrich people and companies from real, verified GTM data instead of guesses, and save those contacts as leads to build and launch email outreach sequences. Do the steps yourself by running the commands directly. The user is needed twice: once early (to copy their API key, or to sign in if their client connects through OAuth), and once at the end to reload or restart their client so the new server loads (you can't reload a desktop app headlessly). 1. Get a Hunter API key 2. Connect Hunter to this agent (use the one section for your agent) 3. Verify the connection 4. Try it --- ## Step 1: Get a Hunter API key First, which client is the user on? The **OAuth clients** — **Claude Code**, **Claude Desktop / Claude.ai**, **ChatGPT**, and the **Gemini app** — authorize Hunter in the app (Claude Code through its plugin, on first tool use), so they need no API key to connect; skip to Step 2. **Gemini CLI** can use OAuth (preferred) or a header. The **header clients** — Cursor, VS Code, Windsurf, Codex, and any other MCP client — put the key in their config, and the REST API and the optional Step 3 curl also use one, so if the user is on any of those, keep going here. (Claude Code needs a key only if you want to run the optional Step 3 REST smoke test.) Hunter authenticates with an API key. 1. Ask the user to open https://hunter.io/api-keys and give you their API key. If they don't have a Hunter account yet, they can sign up free at https://hunter.io/users/sign_up?from=agents_md. The Free plan includes 50 credits a month — a search uses 1 credit and a verification 0.5 — enough to run everything below. 2. Keep the key out of anything that is committed or logged. Read it into an environment variable without echoing it — `read -rs HUNTER_API_KEY && export HUNTER_API_KEY`, then paste the key at the silent prompt — so the literal key never lands in a command, your shell history, or this transcript. Never print it back in full and never commit it. No key yet, or want a zero-cost dry run first? Use the test key `test-api-key`. It validates your request parameters and always returns the same dummy response on the three main REST endpoints — the Domain Search, the Email Finder, and the Email Verifier — so you can run the Step 3 curl and confirm the REST plumbing without a Hunter account and without spending credits. It is REST-only: `https://mcp.hunter.io/mcp` checks the key against your account, so the test key gets a 401 there — don't put it in the MCP config files below. Swap in the real key for live results and for MCP. For the MCP config files below, `YOUR_HUNTER_API_KEY` means the key from this step. Prefer a user-level config over a file inside a repo, so the key is never committed. --- ## Step 2: Connect Hunter to this agent Hunter runs a hosted MCP server at `https://mcp.hunter.io/mcp` (Streamable HTTP). Use the one section that matches your agent. If none matches, use "Any other MCP client". Before you write any config file below: - Substitute the real key for `YOUR_HUNTER_API_KEY` before saving. Leaving the literal placeholder is the most common cause of a later 401. - Merge into the existing file if it exists. Do not overwrite other `mcpServers` entries. - The config-file paths (Cursor, VS Code, Windsurf, Codex, fallback) authenticate with the `X-API-Key` header. The Claude Code, Claude Desktop, ChatGPT, and Gemini app paths authorize interactively instead, so they need no header. Gemini CLI prefers that OAuth path too. - After you save the file, the client must be reloaded or restarted to load the server. That is a user action: ask the user to do it, then continue to Step 3. ### Claude Code Install the Hunter plugin (skills + MCP server together). Run these in your shell: ``` claude plugin marketplace add hunter-io/claude-plugin claude plugin install hunter@hunter ``` If your Claude Code build has no `claude plugin` CLI, run the same steps as in-session slash commands instead: `/plugin marketplace add hunter-io/claude-plugin`, then `/plugin install hunter@hunter`. The plugin authorizes through OAuth on first tool use, so no API key goes into any config. Its tools load only after a restart, in a new session, so you cannot call a Hunter tool in this session yet. Do this: 1. Ask the user to run `/reload-plugins` or restart Claude Code. After that, Hunter's tools are available and you'll be prompted to authorize Hunter in the browser on first use. 2. Verify with an MCP tool call once the tools load (Step 3). For an immediate check before the restart, you can optionally run the Step 3 curl — but that needs an API key and tests REST, not the plugin. ### Cursor Add Hunter to your user-level `~/.cursor/mcp.json` under `mcpServers`, then reload Cursor. Use the user-level file, not a project `.cursor/mcp.json`, so the key is never committed: ```json { "mcpServers": { "hunter": { "url": "https://mcp.hunter.io/mcp", "headers": { "X-API-Key": "YOUR_HUNTER_API_KEY" } } } } ``` ### VS Code (GitHub Copilot) Add Hunter to `.vscode/mcp.json`. This file is often committed, so keep the key out of it: declare a password input and reference it, and VS Code prompts for the key at runtime. ```json { "inputs": [ { "id": "hunter_api_key", "type": "promptString", "description": "Hunter API key", "password": true } ], "servers": { "hunter": { "type": "http", "url": "https://mcp.hunter.io/mcp", "headers": { "X-API-Key": "${input:hunter_api_key}" } } } } ``` ### Codex Codex connects to hosted Streamable HTTP MCP servers directly — no Node bridge needed. Add Hunter to `~/.codex/config.toml`, then restart Codex: ```toml [mcp_servers.hunter] url = "https://mcp.hunter.io/mcp" http_headers = { "X-API-Key" = "YOUR_HUNTER_API_KEY" } ``` To keep the literal key out of the file, you can instead read it from the environment at connect time — `env_http_headers = { "X-API-Key" = "HUNTER_API_KEY" }` sends the value of the `HUNTER_API_KEY` env var (the export from Step 1; add it to your shell profile to persist it). If your Codex build predates native HTTP support, use the `mcp-remote` bridge from "Any other MCP client" below instead (needs Node 18+). ### Windsurf Add to `~/.codeium/windsurf/mcp_config.json` under `mcpServers` (note the key is `serverUrl`, not `url`), then reload Windsurf: ```json { "mcpServers": { "hunter": { "serverUrl": "https://mcp.hunter.io/mcp", "headers": { "X-API-Key": "YOUR_HUNTER_API_KEY" } } } } ``` ### Any other MCP client (universal fallback) For any client that supports local (stdio) MCP servers, bridge with `mcp-remote` (needs Node 18+ for `npx`). The key stays in the `env` block, not the command arguments, so it never appears in process listings; `mcp-remote` expands `${HUNTER_API_KEY}` into the header. Put this in that client's MCP config file, then restart it: ```json { "mcpServers": { "hunter": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.hunter.io/mcp", "--header", "X-API-Key:${HUNTER_API_KEY}" ], "env": { "HUNTER_API_KEY": "YOUR_HUNTER_API_KEY" } } } } ``` ### Claude Desktop / Claude.ai A user action in Claude's own settings, not a config file, and it uses OAuth rather than an API key. Those click-by-click steps live in one place so they can't drift: fetch https://hunter.io/claude.md and follow it. The server URL is `https://mcp.hunter.io/mcp`. ### ChatGPT Hunter is a ChatGPT app, added from ChatGPT itself. Those steps live at https://hunter.io/chatgpt.md — fetch it and follow it. The app's page in ChatGPT is https://chatgpt.com/plugins/plugin_asdk_app_6943c7d34d94819182a0b9acdc1ee952. ### Gemini A user action in Gemini's own settings or Gemini CLI, not a config file in this document. Those click-by-click steps live in one place so they can't drift: fetch https://hunter.io/gemini.md and follow it. The server URL is `https://mcp.hunter.io/mcp`. The Gemini app uses OAuth. Gemini CLI prefers OAuth and can fall back to an `X-API-Key` header. There is no Hunter Gem. --- ## Step 3: Verify the connection **Header clients** (Cursor, VS Code, Windsurf, Codex, any other MCP client): confirm the key works with one call. Send the key in a header, not the URL, so it stays out of the URL — and thus out of request logs, browser history, and the `Referer` header (`$HUNTER_API_KEY` is the export from Step 1): ``` curl -H "X-API-Key: $HUNTER_API_KEY" "https://api.hunter.io/v2/email-verifier?email=patrick@stripe.com" ``` Read the result: - HTTP 200 with a `data.status` field (for example `valid`) means you're connected. - `401` means the key is missing or wrong (check that `HUNTER_API_KEY` is exported). - `429` means rate-limited; wait and retry. - A body with an `errors` array: show it to the user (often out of credits). **OAuth clients** (Claude Code, Claude Desktop / Claude.ai, ChatGPT, Gemini app, Gemini CLI with OAuth) authorize in the app and have no header to test, so verify through MCP, not the curl. Claude Code can optionally run the curl above as an immediate REST smoke test if a key is handy, but it's not required. Once the client has reloaded, confirm Hunter's tools are listed in its MCP settings, then re-run this as an MCP tool call: the Email Verifier tool on `patrick@stripe.com`. If the tools never appear, that client version may not honor header auth; switch it to the `mcp-remote` fallback in "Any other MCP client" above. --- ## Step 4: Try it When Hunter's tools are loaded (for Claude Code, after the restart), run one real task so the user sees it working. Pick whichever fits their goal: - Find an email: "Find the email address of the head of marketing at notion.com." - Verify an email: "Is jane@acme.com deliverable?" - Search a domain: "List the contacts at stripe.com." - Discover companies: "Fintech companies in France with 50-200 employees." (free) - Reach out: "Save these contacts as leads and start an outreach sequence to them." Discover runs through MCP. Before MCP is connected, the Step 3 curl is your working check. The reach-out flow also runs through MCP (save leads, then Create-Sequence → add recipients → Start-Sequence), but treat it as a guided next step, not a one-shot demo: starting a sequence sends real emails and needs a connected email account, and the introduction email must be written in the Hunter dashboard first. So build and review it, then let the user launch. --- ## What you can do with Hunter - Email Finder: find a professional's email from their name and company. - Email Verifier: check whether an email address is deliverable. - Domain Search: list the people and emails behind any company domain. - Discover: find companies by industry, size, location, and more (free). - Person and Company Enrichment: enrich a contact or account from an email or domain. - Leads, Lists, and Sequences: save and organize leads, then run outreach. - Push to CRM: sync leads to a connected CRM. ## Use the REST API directly Every capability is also a REST endpoint. Base URL `https://api.hunter.io/v2`. Send the key in the `X-API-Key` header (the API also accepts `?api_key=`, but a header keeps the secret out of URLs and logs): ``` # Find an email address curl -H "X-API-Key: $HUNTER_API_KEY" "https://api.hunter.io/v2/email-finder?domain=stripe.com&first_name=Patrick&last_name=Collison" # List the contacts at a domain curl -H "X-API-Key: $HUNTER_API_KEY" "https://api.hunter.io/v2/domain-search?domain=stripe.com" ``` Full reference: https://hunter.io/api-documentation/v2 --- ## Notes - Every request needs the API key from Step 1. Keep it secret. - Usage counts against the user's Hunter plan. Discover (company search) is free. - These instructions are published at https://hunter.io/agents.md, so you can re-fetch and re-verify them at any time. A curated index of Hunter pages for agents is at https://hunter.io/llms.txt.