Skip to content

// ai agents and mcp

Via API

Claude Code email verification with pingutil

Ask Claude Code to clean a lead export or build signup validation and it can only guess whether an address is real, because nothing in the repo knows which mailboxes exist or which domains are throwaway. Adding the pingutil MCP server gives it verify_email, verify_emails and lookup_email as tools, so it checks addresses against real mail servers and the disposable list instead of a regex it wrote on the spot.

Where it connects: Claude Code remote MCP server over HTTP (claude mcp add --transport http, or a project .mcp.json)

What goes wrong without it

  • I asked Claude Code to dedupe and import our leads CSV and it did, bounces and temp-mail addresses included.
  • It wrote a disposable-domain check for our signup route from a list it half remembered, and the list is already out of date.
  • Every time I want to know if an address is real I leave the terminal, paste it into some website and come back.

What you can do with Claude Code and pingutil

  • Verify a CSV before an import script runs

    Point Claude Code at leads.csv and ask it to verify the email column in batches of 50 with verify_emails, then write only valid rows to the import file and put risky and unknown ones in a separate review file.

  • Build signup validation from real results

    Have the agent call lookup_email with fast: true on a few test addresses (a mailinator one, a gmail one, a company one), look at category and verdict.is_spam in the results, and then write the signup check against /v1/lookup with those exact field names.

  • Classify domains in a data migration

    While migrating user records, ask Claude Code to classify each distinct domain with lookup_email and add a column for company, free or disposable, so the migration script can tag accounts without a separate pass.

Set it up

  1. 1

    Create an API key in the pingutil dashboard and export it in your shell profile as PINGUTIL_API_KEY, so it never sits in a file the agent edits.

  2. 2

    For yourself across all projects, run claude mcp add with --transport http, --scope user and an Authorization header; the shell expands the variable, so the key is stored in ~/.claude.json, outside the repo.

  3. 3

    For a team project, commit a .mcp.json entry of type http whose header reads Bearer ${PINGUTIL_API_KEY}; Claude Code expands the variable at load time and each person sets their own key.

  4. 4

    Run claude mcp list (or /mcp inside a session) and check that pingutil shows as connected.

  5. 5

    Ask for a check in plain words, for example "verify the emails in leads.csv with pingutil", and approve the tool calls when Claude Code asks.

Terminal: add the pingutil MCP server to Claude Code
# In ~/.zshrc or ~/.bashrc, not in the repo
export PINGUTIL_API_KEY="pk_live_..."   # from https://pingutil.com/dashboard

# Option A: just you, every project (local is the default scope, user = all projects)
claude mcp add --transport http --scope user pingutil https://pingutil.com/mcp \
  --header "Authorization: Bearer $PINGUTIL_API_KEY"

# Option B: shared with the team via version control.
# Commit this as .mcp.json (or merge the entry into an existing one).
# The single-quoted heredoc keeps ${PINGUTIL_API_KEY} literal; Claude Code expands it.
cat > .mcp.json <<'EOF'
{
  "mcpServers": {
    "pingutil": {
      "type": "http",
      "url": "https://pingutil.com/mcp",
      "headers": { "Authorization": "Bearer ${PINGUTIL_API_KEY}" }
    }
  }
}
EOF

claude mcp list   # pingutil should show as connected

What to do with each result

pingutil resultAction in Claude Code
verify_emails: status validKeep the row in the import file the agent writes.
verify_emails: status invalid (mailbox_not_found, no_mx)Drop the row and list it in a rejected.csv with the reason column, so a person can see why.
status risky (accept_all) or unknownMove the row to a review file instead of importing or deleting it; catch-all domains cannot be confirmed.
did_you_mean setHave the agent propose the corrected address in the review file rather than rewriting the data silently.
lookup_email: verdict.is_spam trueUse the reason (disposable_domain or randomized_local_part) as the test case for the signup check the agent is writing.

Limits to plan for

  • verify_email can take several seconds on slow mail servers (up to about 25 s), and a 50-address verify_emails call waits on the slowest of them. Claude Code accepts a per-server "timeout" in milliseconds in .mcp.json if your setup cuts calls short.
  • Claude Code warns when one tool result passes 10,000 tokens and caps it at 25,000 by default (MAX_MCP_OUTPUT_TOKENS), so verify long lists in batches of 50 rather than asking for everything at once.
  • Every tool call counts against the key's account: on the Free plan 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. Over a limit the tool returns a 429 quota_exceeded error. Auth is the API key only, there is no OAuth sign-in.

Claude Code documentation

Claude Code is a trademark of its owner. This integration uses Claude Code's documented extension points; it is not an official Claude Code app.

Common questions

Does Claude see my pingutil API key?
The key travels as an HTTP header that Claude Code adds to its requests to pingutil.com/mcp; the model works with tool names, arguments and results. Keep the key in an environment variable rather than in a repo file, because the agent can read files in the project.
Which scope should I use?
Local (the default) keeps the server to you in the current project, user makes it available in all your projects, and project writes .mcp.json so the whole team gets the same server. With project scope, reference ${PINGUTIL_API_KEY} instead of pasting a key, since the file is committed.
Which tools does the server expose?
Three: verify_email (one address), verify_emails (up to 50 addresses) and lookup_email (category, email signals, spam verdict and, unless fast is true, a company profile). All are read-only.

Stop bad addresses in Claude Code 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 Claude Code setup will receive.