MCP Server
Connect AI agents and MCP-compatible clients to Clearout for email verification, email finding, and other Clearout services.
The Clearout MCP server exposes Clearout's email verification, email finder, name validation, and account tools to AI assistants through the Model Context Protocol. Once connected, your assistant picks the right Clearout tool from a plain-language request, calls it, and reports the result in the same conversation.
There are two ways to run it:
Where it runs
Managed by Clearout at https://mcp.clearout.io/mcp
On your own machine, via npx clearout-mcp
Transport
Streamable HTTP
stdio
Authentication
OAuth 2.1 sign-in with your Clearout account
CLEAROUT_API_TOKEN environment variable
Installation
None
Node.js
Tools
All 14
All 14
Both options call the same Clearout API and return identical results.
Prerequisites
A Clearout account. Create one free at clearout.io and you start with 100 credits, no credit card required.
An MCP-compatible AI client.
Connect to the hosted server
Server URL
https://mcp.clearout.io/mcpCustom connectors are available on Claude and Claude Desktop across the Free, Pro, Max, Team, and Enterprise plans. See Anthropic's setup guide.
Open Settings and go to Connectors.
Click Add, then Add custom connector.
Name it Clearout and paste
https://mcp.clearout.io/mcpas the URL.Click Add, then sign in with your Clearout account when prompted.
Custom MCP connectors run through Developer mode, a beta feature that a workspace admin has to enable first under Workspace Settings > Permissions & Roles > Connected Data. See OpenAI's Developer mode guide.
Ask a workspace admin to turn on Developer mode if it is not already enabled.
Press + and create a developer-mode app for a remote MCP server.
Enter
https://mcp.clearout.io/mcpas the server URL, including the/mcppath.Authorize with your Clearout account when prompted.
Run the server locally (stdio)
The clearout-mcp package runs the same 14 tools on your own machine over stdio. Use it when:
Your client does not support remote MCP servers.
You want the server process running inside your own environment.
You prefer to scope access to a single API token you issue and revoke yourself.
You need Node.js installed and a Clearout API token generated from your Clearout account.
VS Code prompts for the token instead of storing it in the file.
Authentication
Hosted server. The hosted Clearout server is an OAuth 2.1 resource server. When your client first calls it without credentials, the server responds with a challenge pointing at its protected-resource metadata. Your client then walks through the standard OAuth flow and you sign in with your Clearout account. The client ends up holding a scoped, expiring access token, not your password and not a permanent API key. You can revoke that access at any time from your Clearout account.
Local stdio server. The server reads the CLEAROUT_API_TOKEN environment variable and sends it with every Clearout API call. If the variable is missing, the server still starts, but every tool call returns an error until it is set.
Tools reference
The server advertises 14 tools. You rarely call them by name: the assistant chooses the right one from your request. Every tool maps to a documented Clearout API endpoint.
Email verification
email_verify_instant
Verify a single email address immediately.
Read-only
email_verify_bulk_start
Upload a CSV or XLSX file and start a bulk email verification job.
Creates a job
email_verify_bulk_status
Check the status of a bulk email verification job.
Read-only
email_verify_bulk_download
Get the result download URL for a completed bulk verification job.
Read-only
email_verify_bulk_cancel
Cancel an active bulk email verification job. Cannot be undone.
Destructive
email_verify_bulk_remove
Delete a bulk email verification list and its results from Clearout. Cannot be undone.
Destructive
email_verify_instant
email
string (email)
Yes
Email address to verify.
timeout
integer
No
Request wait time in milliseconds. Maximum 180000.
email_verify_bulk_start
file
string
Yes
Base64-encoded CSV or XLSX file content.
optimize
highest_accuracy | fastest_turnaround
No
Verification strategy. Default highest_accuracy.
ignore_duplicate_file
boolean
No
Allow re-uploading a file with the same name and size as a recent upload. Default false.
Returns a list_id to pass to the other bulk tools.
email_verify_bulk_status, email_verify_bulk_download, email_verify_bulk_cancel
list_id
string
Yes
The list_id returned by email_verify_bulk_start.
email_verify_bulk_remove
list_id
string
Yes
The list_id of the job to remove.
ignore_result
boolean
No
Force removal even if a download is currently in progress. Default false.
Email finder
email_finder_instant
Find an email address for a person using their name and company domain.
Read-only
email_finder_bulk_start
Upload a CSV or XLSX file and start a bulk email finder job.
Creates a job
email_finder_bulk_status
Check the status of a bulk email finder job.
Read-only
email_finder_bulk_download
Get the result download URL for a completed bulk email finder job.
Read-only
email_finder_bulk_cancel
Cancel an active bulk email finder job. Cannot be undone.
Destructive
email_finder_bulk_remove
Delete a bulk email finder list and its results from Clearout. Cannot be undone.
Destructive
email_finder_instant
name
string
Yes
Name of the person.
domain
string
Yes
Domain or company name.
timeout
integer
No
Request wait time in milliseconds. Maximum 180000.
queue
boolean
No
Whether discovery can continue in the background.
email_finder_bulk_start
file
string
Yes
Base64-encoded CSV or XLSX file content.
ignore_duplicate_file
boolean
No
Allow re-uploading a file with the same name and size as a recent upload. Default false.
Returns a list_id to pass to the other bulk tools.
email_finder_bulk_status, email_finder_bulk_download, email_finder_bulk_cancel
list_id
string
Yes
The list_id returned by email_finder_bulk_start.
email_finder_bulk_remove
list_id
string
Yes
The list_id of the finder job to remove.
ignore_result
boolean
No
Force removal even if a download is currently in progress. Default false.
Name validation
name_validate
Instantly validate the legitimacy of a person's name to ensure clean data at the point of capture.
Read-only
name_validate
name
string
Yes
The full name or name string to validate.
settings.gibberish_threshold
off | medium | high
No
Sensitivity of the AI model's gibberish detection. Default high.
timeout
integer
No
Request timeout in milliseconds, from 1000 to 10000. Default 8000.
Account
account_credits
Retrieve the total remaining credit balance with a breakdown across subscription, pay-as-you-go, and bonus credits, for individual and organization accounts.
Read-only
account_credits takes no parameters.
Tool behavior hints
Every tool declares MCP annotations so clients know what it does before calling it:
Read-only: instant lookups, verifications, status checks, downloads, and the credit balance.
Creates a job:
email_verify_bulk_startandemail_finder_bulk_start. These are not idempotent, so calling them twice starts two jobs.Destructive: the cancel and remove tools.
Some clients act on these hints. ChatGPT, for example, treats any tool that is not marked read-only as a write action and may ask you to confirm it.
Bulk job lifecycle
Bulk verification and bulk finder jobs follow the same flow:
failed, abandoned, and cancelled are terminal states with no results to download. A job can also fail validation shortly after upload, for example when your account does not have enough credits. Ask your assistant to check account_credits before starting a large job.
Example prompts
"Verify john@example.com for me."
email_verify_instant
A live deliverability verdict.
"Find the email address for John Doe at clearout.io."
email_finder_instant
The business address and confidence score.
"Validate the name Jonathan Smith."
name_validate
A score against Clearout's gibberish and profanity model.
"Check my remaining Clearout credits."
account_credits
The balance by subscription, pay-as-you-go, and bonus credits.
"Verify every email address in this CSV file."
email_verify_bulk_start
A bulk job that is tracked to completion, with a download link.
"Find business emails for the contacts in this spreadsheet."
email_finder_bulk_start
A bulk finder run with the results collected for you.
Credits and limits
Credits are charged exactly as they are everywhere else in Clearout. A verification through MCP costs the same as one run from the dashboard or the API, and a bulk job costs the same as uploading that file yourself. Rate limits and plan entitlements are also identical.
Troubleshooting
The Clearout tools do not appear (hosted server)
Check that the URL is exactly
https://mcp.clearout.io/mcp, including the/mcppath. Dropping the path is the most common mistake.Make sure you completed the sign-in prompt. If you dismissed it, remove the connector and add it again.
In ChatGPT, confirm that a workspace admin has enabled Developer mode.
Check your network. Anthropic requires connectors to be reachable over the public internet from its IP ranges, so a VPN or corporate firewall can block the connection.
The Clearout tools do not appear (local stdio server)
Restart your client after editing its config.
Check that
CLEAROUT_API_TOKENis set and spelled correctly.Make sure your installed Node.js version meets the package's requirement.
A bulk job failed right after upload
The most common cause is insufficient credits. Check your balance with account_credits, top up, and start the job again. If you re-upload the same file soon after, set ignore_duplicate_file to true.
FAQ
Related
Last updated
Was this helpful?

