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

Eight 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

get_credit_balance

Show how many validation credits the account has. Your assistant uses it when you ask about your balance, before a large validation, or when a validation stops because credits ran out.

• Input: none
• Output:
  • available_credits — credits you can spend right now. This is the number to check before validating.
  • balance — total credits, including any reserved for batches that are still running
  • reserved_credits — credits set aside for running batches
  • auto_topup — enabled, credit_amount, threshold, disabled_reason
  • credit_costs — what each validation outcome costs (see Credit usage)
  • billing_url — where to buy credits or turn on auto top-up
  • On Unlimited plans, also unlimited_standard_validations: true and enhanced_grant (remaining, total, period_end) for the monthly enhanced allotment
• Consumes credits: no

Accounts on older plans that don’t use credits get uses_credits: false and a link to the billing page instead.

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: fast, accurate (default), enhanced, or thorough — see validation strategies)
• Output: email, state, sub_state, suggestion, domain, canonical, mx_record, first_name, last_name, verified_at, is_valid, is_deliverable
• Consumes credits: yes — see Credit usage

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: yes, per email — see Credit usage. If credits run out partway through, the results so far are returned with a stopped_reason.

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, credits_needed, created_at, and the same progress counters as list_batches
• Consumes credits: yes, per email — see Credit usage. Credits are reserved when the batch starts. If there aren’t enough, the batch pauses in the credits_exhausted state, credits_needed shows how many it needs, and it resumes automatically after you buy credits.

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

Credit usage

Enhanced checks run only when you pass validation_strategy: "enhanced". Every call validates the address again; results aren’t served from a cache.

On Unlimited plans, standard validations are free. Enhanced validations use the monthly allotment first, then credits.

If you run out, your assistant gets a message with a link to buy credits at app.truelist.io/settings/billing. You can also turn on auto top-up there so credits refill automatically.

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.