MCP Server

Truelist’s hosted MCP (Model Context Protocol) server. Let Claude, Cursor, VS Code Copilot, and any other MCP-capable AI assistant validate emails, manage batches, and explore your account — all from inside a chat.

No package to install. No API key to copy. Paste a URL, log in to Truelist once, and you’re connected.

Quick start

The MCP server lives at:

https://api.truelist.io/mcp

When your AI assistant first connects, it opens your browser to log in via Truelist. After that, it’s authenticated until you revoke access. No API keys to manage.

Configuration

Claude Desktop

Edit your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "truelist": {
      "url": "https://api.truelist.io/mcp"
    }
  }
}

Restart Claude Desktop. On first use, it will open a browser window asking you to authorize Truelist. Approve, and you’re connected.

Claude Code

claude mcp add --transport http truelist https://api.truelist.io/mcp

Authorize the same way — Claude Code opens your browser the first time it talks to a tool.

Cursor

Add to .cursor/mcp.json (project-level) or your global Cursor MCP settings:

{
  "mcpServers": {
    "truelist": {
      "url": "https://api.truelist.io/mcp"
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json:

{
  "servers": {
    "truelist": {
      "url": "https://api.truelist.io/mcp"
    }
  }
}

What you can do

Once connected, you can ask your assistant things like:

• “Is jane@example.com a real, deliverable address?”
• “Validate these 30 addresses from my latest HubSpot export.”
• “Create a Truelist batch named ‘Q3 newsletter cleanup’ with this list.”
• “Which of my recent batches has the most invalid emails?”
• “Show me every disposable address Truelist found in batch a3b9....”
• “What plan am I on and how many credits do I have left?”

Tools

Seven tools are available. Your assistant picks the right one based on what you ask.

check_account

Show the connected account’s name, plan, and connected user. Useful as a sanity check or when you have multiple Truelist accounts.

• Input: none
• Output: account.id, account.name, account.payment_plan, user.email, user.name, user.time_zone
• Consumes credits: no

validate_email

Validate a single email address. Runs Truelist’s full validation chain — syntax, MX, SMTP, plus enhanced checks where applicable.

• Input: email (required), validation_strategy (optional: safest_bet or highest_reach)
• Output: email, state, sub_state, suggestion, domain, canonical, mx_record, first_name, last_name, verified_at, is_valid, is_deliverable
• Consumes credits: 1 per validation (cached results from recent validations may be returned for free)

validate_emails

Validate up to 50 email addresses in one call. Returns one result per email plus aggregate counts. If a rate limit or paywall trips mid-batch, returns the partial results plus a clear stopped_reason.

• Input: emails (array, max 50), validation_strategy (optional)
• Output: results[], succeeded, failed, total, optional stopped_reason and stopped_at_index
• Consumes credits: 1 per email validated

For larger lists, use create_batch.

create_batch

Create a new validation batch from a JSON list of email addresses. Batches process asynchronously and produce CSV downloads when complete.

• Input: name (required), emails (array, max 10,000), validation_strategy (optional)
• Output: id, name, batch_state, email_count, created_at, and the same progress counters as list_batches
• Consumes credits: 1 per email validated (cache hits don’t consume)

list_batches

List validation batches the account has created, with progress counters and optional filtering.

• Input: limit (default 20, max 100), offset, batch_state, search
• Output: total_count, limit, offset, has_more, next_offset, batches[]
• Consumes credits: no

get_batch

Get full detail for one batch, including CSV download URLs when the batch is complete.

• Input: batch_id (required — the UUID returned by list_batches or create_batch)
• Output: all the fields from list_batches, plus safest_bet_csv_url, highest_reach_csv_url, only_invalid_csv_url, annotated_csv_url
• Consumes credits: no

list_email_addresses

List previously-validated email addresses from your account’s history, filtered by batch or validation state.

• Input: one of batch_uuid or email_state is required. Optional: email_sub_state, email_address, limit (default 25, max 100), offset.
• Output: total_count, limit, offset, has_more, next_offset, email_addresses[]
• Consumes credits: no

Validation states

Common sub-states: email_ok, accept_all, is_disposable, is_role, failed_mx_check, failed_no_mailbox, failed_smtp_check, failed_syntax_check, failed_spam_trap.

Revoking access

Connected apps live under your Truelist account. To disconnect an AI assistant, sign in to app.truelist.io and revoke the connection. Your assistant will be prompted to reconnect the next time it tries to use Truelist.

Troubleshooting

“Authentication required” or 401 on every request

Your token has expired or been revoked. Reconnect by triggering a new tool call — your assistant will open the browser to re-authorize.

Browser opens but doesn’t redirect back

Make sure you’re logging in to Truelist with the same browser your AI assistant opened. The OAuth handshake uses a temporary callback URL that the assistant is listening on locally.

My assistant doesn’t see Truelist tools

1. Restart the assistant after changing its MCP config.
2. Confirm the config file is valid JSON (no trailing commas, etc.).
3. Confirm the URL is exactly https://api.truelist.io/mcp (HTTPS, no trailing slash).

Rate limits

Truelist enforces per-account rate limits on validations. If you hit one, your assistant will surface a message explaining what happened and how to wait or upgrade.