// ai agents and mcp
Via APIGemini CLI email verification with pingutil
Gemini CLI can sort and rewrite a contacts file in seconds, but it cannot know whether an address bounces. An mcpServers entry with httpUrl pointing at pingutil gives it the verification and classification tools, and settings.json expands $PINGUTIL_API_KEY so the key stays in your environment.
Where it connects: Gemini CLI settings.json mcpServers entry with httpUrl (Streamable HTTP) and headers
What goes wrong without it
- Gemini rewrote our mailing list file and every typo survived.
- I run agents in scripts and need the config to work without anyone typing a key.
- I keep asking the model whether a domain is a real company and it just makes something up.
What you can do with Gemini CLI and pingutil
Verify a list from the terminal
Ask Gemini CLI to verify the addresses in a text file with verify_emails, in groups of 50, and print a summary of valid, invalid, risky and unknown with reasons.
Classify domains for a report
Give it a list of signup domains and ask for a category per domain from lookup_email with fast: true, so the report separates company, free webmail and disposable signups.
Answer "who is this company" from data
For a single domain, lookup_email returns a company profile with confidence, so the answer comes from pingutil's lookup rather than the model's memory.
Set it up
- 1
Create an API key in the pingutil dashboard and export it as PINGUTIL_API_KEY.
- 2
Open ~/.gemini/settings.json for all projects (or .gemini/settings.json in one project) and add a pingutil entry under mcpServers.
- 3
Set httpUrl to https://pingutil.com/mcp and an Authorization header of Bearer $PINGUTIL_API_KEY; Gemini CLI expands environment variables in settings.json string values.
- 4
Leave trust at false so Gemini asks before each tool call, or set it to true once you are comfortable with the calls it makes.
- 5
Start gemini, run /mcp to see the pingutil tools, and ask for a check.
{
"mcpServers": {
"pingutil": {
"httpUrl": "https://pingutil.com/mcp",
"headers": {
"Authorization": "Bearer $PINGUTIL_API_KEY"
},
"timeout": 120000,
"trust": false
}
}
}What to do with each result
| pingutil result | Action in Gemini CLI |
|---|---|
| status valid | Count the address as deliverable in the summary. |
| status invalid with did_you_mean | Print the suggested fix next to the address. |
| status risky or unknown | List separately as unconfirmed, not as bad. |
| lookup_email: category disposable | Count as a throwaway signup in the domain report. |
| company.confidence low | Report the company match as uncertain instead of stating it as fact. |
Limits to plan for
- Gemini CLI's default request timeout is 600,000 ms; the example lowers it to 120 s so a stuck batch fails sooner. Mailbox checks on slow mail servers can take up to about 25 s each.
- gemini mcp add --transport http with --header also works, but the shell expands $PINGUTIL_API_KEY before Gemini saves it, so the key ends up in settings.json (project scope by default). Editing the file keeps the variable reference instead.
- Calls count toward the key's Free plan limits: 300 verifications a day and 3,000 a month, 2,000 lookups a day and 30,000 a month, 50 new company profiles a day and 500 a month. No OAuth.
Gemini CLI documentation
Gemini CLI is a trademark of its owner. This integration uses Gemini CLI's documented extension points; it is not an official Gemini CLI app.
Common questions
- httpUrl or url?
- httpUrl. In Gemini CLI, httpUrl is the Streamable HTTP endpoint, which is what pingutil serves. pingutil does not offer an SSE stream.
- Does Gemini see my API key?
- Gemini CLI adds the header to its requests; the model gets tool results. Keep the key in the environment, not in a project settings file that is committed.
- Which tools does the server expose?
- verify_email, verify_emails (up to 50 addresses) and lookup_email, all read-only.
Stop bad addresses in Gemini CLI today
Sign in with your email, create an API key and paste it into the step above. Test on a few real addresses first: the live demo shows exactly what your Gemini CLI setup will receive.