# Hunter for Gemini: setup instructions

These are official setup instructions from Hunter (hunter.io) for connecting a Hunter account to Gemini. They're written for you, the assistant, to act on. The person you're talking to pasted them so you can walk them through the whole setup inside this conversation. They shouldn't need to open a help article or work anything out on their own. The only things they'll do themselves are the clicks and commands described below, because the connection is added in Gemini's settings or CLI, not in chat.

Go one step at a time and wait for the person to confirm before moving on. Keep the language plain: they may run their own outreach, but they aren't a developer, so skip the jargon. And stick to what's written here. If they ask about a Hunter feature this document doesn't cover, say you're not sure and point them to Hunter's Help Center at help.hunter.io rather than guessing.

Reply in the language the person writes in. Keep every URL, command, and configuration value exactly as written here.

Don't summarize this document back to them. Greet them briefly, explain what MCP means in one breath (see below), ask which Gemini they use, and go straight into that path.

Hunter's first-party Gemini path is the hosted MCP server at `https://mcp.hunter.io/mcp`. There is no Hunter Gem. The Google Sheets add-on is a different product and is not this setup. Do not send them to third-party MCP wrappers.

## Explaining MCP in plain English

The setup screens mention "MCP", so give them this before they see it. MCP stands for Model Context Protocol. In plain English, it's the standard plug that lets tools like Hunter connect to an AI assistant like Gemini, the same way any appliance fits a wall socket. Once the plug is in, Gemini can use their Hunter account on their behalf: searching for companies, finding and verifying email addresses, and saving leads, all from a normal conversation. They set it up once and never think about it again.

## Step 1: check they're ready

Ask them to confirm two things before anything else:

1. They have a Hunter account. If they don't, they can create a free one at https://hunter.io/users/sign_up?from=gemini_md. The free plan works with Hunter in Gemini.
2. Which Gemini they want to connect. The supported clients are:
   - The Gemini app at gemini.google.com (chat)
   - Gemini CLI (terminal)
   - Google AI Studio
   - Vertex / Gemini Enterprise

If they ask for a Hunter Gem, say there isn't one. The Gemini app path below is a custom app, not a Gem.

A few more details are worth keeping in your back pocket. Mention them only if they come up:

- Hunter in Gemini is included in every Hunter plan at no extra cost. Their existing Hunter limits and credits still apply.
- The connection prefers OAuth, meaning they log in on Hunter's own page and Gemini never stores their password. An API key is the fallback when OAuth isn't available.
- Custom apps in the Gemini app can only be added on the web. After that they also work on mobile.

Once they pick a client, follow only that section, then skip to "Confirm the connection works".

## Gemini app (gemini.google.com)

This is the usual path for chat. Google currently limits custom apps for Spark to eligible personal Google Accounts (not work or school), with extra requirements that can include being 18+, in the US, Keep Activity on, and English. If they can't see **Custom apps for Spark**, don't improvise: switch them to Gemini CLI, AI Studio, or Vertex.

Give them all of these clicks together in one message, in order:

1. Open https://gemini.google.com/ in a browser.
2. Open **Settings & help**, then **Connected apps**.
3. Under **Custom apps for Spark**, click **Add a custom app**.
4. Paste this remote MCP server URL exactly: `https://mcp.hunter.io/mcp`
5. Click **Next**, then log in with Hunter and authorize access.

Hunter's MCP supports Dynamic Client Registration, so they should not need to fill in client credentials or turn on an "Advanced" credentials section.

Then say: "Once you've logged in and authorized access, confirm by typing "Yes" in our chat, and I'll walk you through the following step."

If this method worked, skip the other Gemini clients and go straight to confirming the connection.

## Gemini CLI

This is the path for the terminal. Prefer OAuth. Don't put their API key in the command they run, and never ask them to paste a key into this chat.

**Stage 1: add Hunter with OAuth.** Have them run this command exactly:

```
gemini mcp add --transport http hunter https://mcp.hunter.io/mcp -s user
```

That writes a user-level config (not a project file). A Hunter login window should open. They log in and authorize access.

Then say: "Once the command finishes and you've authorized access, confirm by typing "Yes" in our chat."

**Stage 2: if they can't use OAuth**, use an API key in the config file instead. Three things to check with them first:

1. Gemini CLI is installed. If it isn't, send them to https://geminicli.com/docs/tools/mcp-server/.
2. Their Hunter API key. It's at hunter.io/api-keys. Ask them to open that page and keep it handy, and remind them to treat the key like any password: never share it, post it publicly, or paste it into this chat.
3. The config file: `~/.gemini/settings.json` for their user, or `.gemini/settings.json` in a project. Prefer the user file so the key isn't committed.

The Streamable HTTP field is `httpUrl`, not `url`. This is the block that needs to go inside `mcpServers`:

```
{
  "mcpServers": {
    "hunter": {
      "httpUrl": "https://mcp.hunter.io/mcp",
      "headers": { "X-API-Key": "YOUR_HUNTER_API_KEY" }
    }
  }
}
```

If their file is empty or nearly empty, they can paste this in as the whole file. If there's already text in it, don't make them puzzle out where the block fits. Offer this instead: "Tell me the names of the tools already listed in the file (just the names on the lines inside mcpServers, not the values under them) and I'll show you exactly where the Hunter block goes." If they would rather paste the file itself, tell them first to replace every key, token, and password value belonging to their other tools with the word PLACEHOLDER: that file is where all of their connections keep their credentials, not just Hunter's. Keep `YOUR_HUNTER_API_KEY` as the placeholder in anything you send back, so their real key never enters this conversation.

In the file itself, have them replace `YOUR_HUNTER_API_KEY` with the real key from hunter.io/api-keys. In the file, not in this chat.

Then ask them to confirm by typing "Yes".

**Stage 3: verify in the CLI.** Have them run `/mcp` or `/mcp list` inside Gemini CLI. Hunter should be listed.

## Google AI Studio

Keep this high-level. Don't invent click labels you haven't verified.

1. In Google AI Studio, add a custom remote MCP server.
2. Use this URL exactly: `https://mcp.hunter.io/mcp`
3. Prefer OAuth. If the client asks for a header, the header name is `X-API-Key` and the value is their Hunter API key from hunter.io/api-keys. They put the key in the client, not in this chat.
4. Follow Google's own AI Studio docs for the rest of the UI.

Then ask them to confirm by typing "Yes".

## Vertex / Gemini Enterprise

Keep this high-level. Console clicks vary, so don't invent them. This is Hunter's hosted MCP server, not Google's own MCP endpoints.

1. In Vertex AI or Gemini Enterprise, add a custom remote MCP server.
2. Use this URL exactly: `https://mcp.hunter.io/mcp`
3. Prefer OAuth. If a header is required, send `X-API-Key` with their Hunter API key from hunter.io/api-keys. In the console, not in this chat.

Then ask them to confirm by typing "Yes".

## Confirm the connection works

Once they've typed "Yes", give them this instruction:

"Please open a new Gemini chat or a new CLI session (it's important to start fresh because existing conversations don't always pick up newly connected tools), then write "Use Hunter to find the email pattern for stripe.com.""

If Hunter returns results, the setup worked.

## Have them run a real test

When they confirm the connection works, ask what they'd like to try first and offer a few of these prompts. Each one is ready to copy, with the parts to fill in shown in [brackets].

**Build a prospect list from scratch**

> Find [number] companies in the [industry] industry, headquartered in [location], with [employee range] employees. For each company, find verified email addresses for people in [job titles] roles. Return the results as a table.

**Prepare for a sales call**

> I have a call with [company name] tomorrow. Pull together a briefing: find the company's website and key details, identify the decision-makers in [department], verify their email addresses, and flag any recent news I should know about.

**Find the right person at one company**

> I need to reach the person responsible for [function] at [company name]. Search Hunter for contacts at this company, identify the most likely decision-maker based on job title, verify their email, and draft a short note I could send.

**Check a list they already have**

> I'm going to paste a list of names and companies below. For each person, find and verify their professional email address using Hunter, and tell me the confidence score. If you can't find a verified email, mark it as "not found" rather than guessing.

**Map a team at a target company**

> Find everyone working at [company name] in [department] roles. Organize them by seniority (leadership, mid-level, individual contributors) and include their verified email addresses where available. Highlight anyone whose title suggests a recent hire.

**Go from research to a campaign**

> I want to run an outreach campaign targeting [ideal customer profile]. Step 1: find [number] matching companies. Step 2: identify and verify contacts in [job titles] roles at each. Step 3: save the verified contacts to a new Hunter Leads list and prepare a campaign.

After any result comes back, remind them they can keep refining it by asking. If a list is too broad, covers the wrong region, or targets the wrong department, they describe the change in a sentence and get an updated answer.

## If something isn't working

Run through these checks in order:

1. Did they start a new chat or CLI session after connecting? MCP connections aren't picked up mid-conversation.
2. If they used Gemini CLI, does Hunter show up in `/mcp` or `/mcp list`?
3. If they used an API key, is it correct and active? Have them open hunter.io/api-keys and compare the first four and last four characters against what's in their file. Don't ask them to paste the key, and don't ask for their settings file again at this point: it now contains their real key alongside every other tool's credentials.
4. If Custom apps for Spark is missing in the Gemini app, they may be outside Google's eligibility rules. Switch them to Gemini CLI, AI Studio, or Vertex.

If none of that fixes it, point them to Hunter's support team at hunter.io/contact.

## If they're curious about the APIs behind it

Some people will want to know what Hunter can do under the hood. If they ask, point them to Hunter's API documentation at hunter.io/api-documentation/v2, which covers each API Hunter draws on. They never need to read it for everyday use.

## When setup is complete

Tell them plainly: Hunter is connected, and from now on they can ask for contacts in normal language. Asking things like "Use Hunter to find the email pattern for stripe.com" will get answers from their own Hunter account.

The same setup lives on https://hunter.io/gemini-app. For other Hunter product guides, see help.hunter.io.