// ai agents and mcp
Via APICodex email verification with pingutil
Codex will happily write an email-cleaning script, but the script can only check syntax because nothing tells it which mailboxes exist. A four-line [mcp_servers.pingutil] entry in config.toml gives Codex the pingutil tools, with the API key read from an environment variable through bearer_token_env_var so it never lands in the config file.
Where it connects: Codex config.toml [mcp_servers.<name>] streamable HTTP entry with url and bearer_token_env_var
What goes wrong without it
- Codex wrote us a beautiful lead cleaner that validates the regex and nothing else.
- I do not want our API key pasted into config.toml where it ends up in dotfile backups.
- Our default 60-second tool timeout and a slow corporate mail server do not get along.
What you can do with Codex and pingutil
Clean a lead file in a Codex task
Ask Codex to verify the email column of a CSV with verify_emails, 50 at a time, and write valid, review and rejected files based on status. The verification happens through the tool, the file handling in code.
Generate test fixtures from real classifications
Have Codex call lookup_email with fast: true on sample addresses and save the responses as JSON fixtures, so the tests for your own signup code use the real response shape.
Spot-check a support or sales export
Before a bulk reply or sequence, ask Codex to classify the sender domains with lookup_email and report how many are disposable, free webmail or company addresses.
Set it up
- 1
Create an API key in the pingutil dashboard and export it as PINGUTIL_API_KEY in the shell that starts Codex.
- 2
Add an [mcp_servers.pingutil] table to ~/.codex/config.toml (or .codex/config.toml in a trusted project) with url = "https://pingutil.com/mcp" and bearer_token_env_var = "PINGUTIL_API_KEY". Alternatively run codex mcp add pingutil --url https://pingutil.com/mcp and add the bearer_token_env_var line by hand.
- 3
Raise tool_timeout_sec above the 60-second default if you verify batches against slow mail servers.
- 4
Optionally restrict the tools with enabled_tools, for example only lookup_email for a classification-only setup.
- 5
Start Codex, check that the server loads, and ask it to verify or classify addresses with pingutil.
# In ~/.zshrc or ~/.bashrc
export PINGUTIL_API_KEY="pk_live_..." # from https://pingutil.com/dashboard
# Append the server to Codex's user config (TOML)
cat >> ~/.codex/config.toml <<'EOF'
[mcp_servers.pingutil]
url = "https://pingutil.com/mcp"
bearer_token_env_var = "PINGUTIL_API_KEY" # sent as Authorization: Bearer <value>
tool_timeout_sec = 120 # default is 60
# enabled_tools = ["lookup_email"] # optional allow list
EOFWhat to do with each result
| pingutil result | Action in Codex |
|---|---|
| verify_emails: status valid | Write the row to valid.csv for import. |
| status invalid | Write the row to rejected.csv with the reason (mailbox_not_found, no_mx, disposable_domain). |
| status risky or unknown | Write the row to review.csv; Codex should not delete catch-all or unreachable addresses on its own. |
| lookup_email: category free or isp | Mark the lead as a personal address in the report Codex produces. |
| tool error 429 quota_exceeded | Have Codex stop the batch loop and report how many rows are left, instead of retrying. |
Limits to plan for
- Codex gives each tool call 60 seconds by default (tool_timeout_sec). A verify_emails batch waits on its slowest mail servers, so raise the timeout or use smaller batches.
- The key is read from the environment named in bearer_token_env_var; if the variable is missing in the shell that starts Codex, every call fails with 401. The current Codex docs list no experimental flag for HTTP servers; if an older build ignores the url entry, update Codex.
- Calls count against the key's account limits (Free plan: 300 verifications a day and 3,000 a month, 2,000 lookups a day and 30,000 a month). The server uses API-key auth only, no OAuth.
Codex documentation
Codex is a trademark of its owner. This integration uses Codex's documented extension points; it is not an official Codex app.
Common questions
- bearer_token_env_var or http_headers?
- bearer_token_env_var. It names an environment variable and Codex sends its value as Authorization: Bearer, so the key is not stored in config.toml. http_headers holds static values and would put the key in the file.
- Does Codex see my API key?
- Codex reads the variable to build the request header; the model works with the tool calls and their results. Keep the key out of project files, since the agent can read the repo.
- Which tools will Codex get?
- verify_email, verify_emails and lookup_email. Use enabled_tools if you want only some of them available in a project.
Stop bad addresses in Codex 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 Codex setup will receive.