> For the complete documentation index, see [llms.txt](https://docs.clearout.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clearout.io/developers/mcp.md).

# 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](https://modelcontextprotocol.io/). 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.

{% hint style="info" %}
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.
{% endhint %}

## Prerequisites

* A Clearout account. [Create one free at clearout.io](https://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/mcp
```

{% stepper %}
{% step %}

## Add the server URL

Add the server URL to your AI client using the steps for that client below.
{% endstep %}

{% step %}

## Sign in

Sign in with your Clearout account when your client prompts you.
{% endstep %}

{% step %}

## Use Clearout tools

The Clearout tools appear in your client, ready to use.
{% endstep %}
{% endstepper %}

{% tabs %}
{% tab title="Claude" %}
Custom connectors are available on Claude and Claude Desktop across the Free, Pro, Max, Team, and Enterprise plans. See [Anthropic's setup guide](https://support.anthropic.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp).

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.
   {% endtab %}

{% tab title="ChatGPT" %}
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](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt).

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.
   {% endtab %}

{% tab title="Claude Code" %}
{% code title="Terminal" %}

```bash
# Add the hosted Clearout MCP server over HTTP
claude mcp add --transport http clearout https://mcp.clearout.io/mcp

# Claude Code opens the sign-in flow on first use
claude mcp list
```

{% endcode %}
{% endtab %}

{% tab title="Cursor" %}
{% code title=".cursor/mcp.json" %}

```json
{
  "mcpServers": {
    "clearout": {
      "url": "https://mcp.clearout.io/mcp"
    }
  }
}
```

{% endcode %}
{% endtab %}

{% tab title="VS Code" %}
{% code title=".vscode/mcp.json" %}

```json
{
  "servers": {
    "clearout": {
      "type": "http",
      "url": "https://mcp.clearout.io/mcp"
    }
  }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="info" %}
Using a different client? Any client that supports remote MCP servers over Streamable HTTP can connect to `https://mcp.clearout.io/mcp`.
{% endhint %}

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

{% tabs %}
{% tab title="Claude Desktop" %}
{% code title="claude\_desktop\_config.json" %}

```json
{
  "mcpServers": {
    "clearout": {
      "command": "npx",
      "args": ["clearout-mcp"],
      "env": {
        "CLEAROUT_API_TOKEN": "your-clearout-api-token"
      }
    }
  }
}
```

{% endcode %}
{% endtab %}

{% tab title="Claude Code" %}
{% code title="Terminal" %}

```bash
claude mcp add clearout \
  -e CLEAROUT_API_TOKEN=your-clearout-api-token \
  -- npx clearout-mcp
```

{% endcode %}
{% endtab %}

{% tab title="Cursor" %}
{% code title=".cursor/mcp.json" %}

```json
{
  "mcpServers": {
    "clearout": {
      "command": "npx",
      "args": ["clearout-mcp"],
      "env": {
        "CLEAROUT_API_TOKEN": "your-clearout-api-token"
      }
    }
  }
}
```

{% endcode %}
{% endtab %}

{% tab title="VS Code" %}
VS Code prompts for the token instead of storing it in the file.

{% code title=".vscode/mcp.json" %}

```json
{
  "inputs": [
    {
      "id": "clearout-token",
      "type": "promptString",
      "description": "Clearout API token",
      "password": true
    }
  ],
  "servers": {
    "clearout": {
      "command": "npx",
      "args": ["clearout-mcp"],
      "env": {
        "CLEAROUT_API_TOKEN": "${input:clearout-token}"
      }
    }
  }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Treat `CLEAROUT_API_TOKEN` like any other secret. Use one token per environment, keep it out of version control, and revoke it from your Clearout account if it is ever exposed. Restart your client after editing its config.
{% endhint %}

## Authentication

**Hosted server.** The hosted Clearout server is an [OAuth 2.1](broken://pages/c25186bb3bbeee6236c65f95cbfa2091954fc0c7) 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](/developers/api.md) 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:

{% stepper %}
{% step %}

## Start

`*_bulk_start` uploads the file and returns a `list_id`.
{% endstep %}

{% step %}

## Poll

`*_bulk_status` returns a `progress_status`. Keep polling while it is `pending`, `queued`, or `running`.
{% endstep %}

{% step %}

## Download

When the status is `completed`, `*_bulk_download` returns a URL for the results file.
{% endstep %}

{% step %}

## Clean up (optional)

`*_bulk_cancel` stops a running job. `*_bulk_remove` deletes the list and its results.
{% endstep %}
{% endstepper %}

`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

<details>

<summary>Should I use the hosted or the local server?</summary>

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.

</details>

<details>

<summary>How is this different from the Clearout API?</summary>

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.

</details>

<details>

<summary>Which Clearout plan do I need?</summary>

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.

</details>

## Related

* [Clearout MCP product page](https://clearout.io/mcp/)
* [Clearout API documentation](/developers/api/overview.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.clearout.io/developers/mcp.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.