Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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:

Hosted (recommended)
Local stdio

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.

The MCP server is free to use. Tool calls consume the same Clearout credits as the dashboard and the REST API. Any plan works, including the free tier.

Prerequisites

Connect to the hosted server

Server URL

https://mcp.clearout.io/mcp
1

Add the server URL

Add the server URL to your AI client using the steps for that client below.

2

Sign in

Sign in with your Clearout account when your client prompts you.

3

Use Clearout tools

The Clearout tools appear in your client, ready to use.

Custom connectors are available on Claude and Claude Desktop across the Free, Pro, Max, Team, and Enterprise plans. See Anthropic's setup guide.

  1. Open Settings and go to Connectors.

  2. Click Add, then Add custom connector.

  3. Name it Clearout and paste https://mcp.clearout.io/mcp as the URL.

  4. 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.

  1. Ask a workspace admin to turn on Developer mode if it is not already enabled.

  2. Press + and create a developer-mode app for a remote MCP server.

  3. Enter https://mcp.clearout.io/mcp as the server URL, including the /mcp path.

  4. Authorize with your Clearout account when prompted.

Using a different client? Any client that supports remote MCP servers over Streamable HTTP can connect to https://mcp.clearout.io/mcp.

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

Tool
Description
Behavior

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

Parameter
Type
Required
Description

email

string (email)

Yes

Email address to verify.

timeout

integer

No

Request wait time in milliseconds. Maximum 180000.

email_verify_bulk_start

Parameter
Type
Required
Description

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

Parameter
Type
Required
Description

list_id

string

Yes

The list_id returned by email_verify_bulk_start.

email_verify_bulk_remove

Parameter
Type
Required
Description

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

Tool
Description
Behavior

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

Parameter
Type
Required
Description

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

Parameter
Type
Required
Description

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

Parameter
Type
Required
Description

list_id

string

Yes

The list_id returned by email_finder_bulk_start.

email_finder_bulk_remove

Parameter
Type
Required
Description

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

Tool
Description
Behavior

name_validate

Instantly validate the legitimacy of a person's name to ensure clean data at the point of capture.

Read-only

name_validate

Parameter
Type
Required
Description

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

Tool
Description
Behavior

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_start and email_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:

1

Start

*_bulk_start uploads the file and returns a list_id.

2

Poll

*_bulk_status returns a progress_status. Keep polling while it is pending, queued, or running.

3

Download

When the status is completed, *_bulk_download returns a URL for the results file.

4

Clean up (optional)

*_bulk_cancel stops a running job. *_bulk_remove deletes the list and its results.

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

You ask
Tool called
What you get

"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 /mcp path. 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_TOKEN is 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

Should I use the hosted or the local server?

Use the hosted server unless you have a specific reason not to. It needs no installation, stays up to date automatically, and authenticates over OAuth so no long-lived key sits in a config file. Use the local stdio server when your client does not support remote MCP servers, when you want the process inside your own environment, or when you prefer to scope access to a single API token you control.

How is this different from the Clearout API?

Both reach the same engine and return the same results. With the REST API you build and maintain the integration yourself. With MCP, your AI assistant reads a plain-language request, selects the right tool, fills in the parameters, and explains the result. The API remains the right choice for production systems and automated pipelines.

Which Clearout plan do I need?

Any plan works, including the free tier. MCP access is not gated behind a specific plan. What you can do mirrors your account's credits and entitlements.

Last updated

Was this helpful?