MCP integration

MCP setup

ValidationApp hosts a Model Context Protocol (MCP) server so AI assistants like Cursor, Claude Code, and VS Code Copilot can validate emails, upload lists, run batch jobs, and check credits using your existing API key — no local npm install required.

Endpoint

The MCP server uses Streamable HTTP on the same host as the REST API. Use your production or stage API base URL plus /api/mcp.

POST /api/mcp
GET  /api/mcp

Authentication

Send your live API key (va_live_…) from Dashboard → API Keys. Use Bearer in Authorization or pass X-API-Key. Disabled keys return HTTP 401.

Authorization: Bearer va_live_xxxxxxxx
X-API-Key: va_live_xxxxxxxx

Use a validation-scoped API key (va_live_…) from Dashboard → API Keys. Disabled keys return HTTP 401.

Shared HTTP config

Most MCP clients accept this JSON shape. Set "type": "http" (Claude Code also accepts "streamable-http"). Prefer environment variables for the key.

{
  "mcpServers": {
    "validationapp": {
      "type": "http",
      "url": "https://validationapp.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${VALIDATIONAPP_API_KEY}"
      }
    }
  }
}

Cursor

In Cursor settings, add a remote MCP server with your API URL and Bearer header. Replace the placeholder key with your va_live_ key from the dashboard.

{
  "mcpServers": {
    "validationapp": {
      "url": "https://validationapp.com/api/mcp",
      "headers": {
        "Authorization": "Bearer va_live_xxxxxxxx"
      }
    }
  }
}

Claude Code

Use the CLI or add to ~/.claude.json / project .mcp.json. Run /mcp in a session to verify the connection.

claude mcp add --transport http validationapp https://validationapp.com/api/mcp --header "Authorization: Bearer $VALIDATIONAPP_API_KEY"

VS Code + GitHub Copilot

Add .vscode/mcp.json (or user MCP settings) with "type": "http", your /api/mcp URL, and Bearer header. Requires Copilot agent/MCP features.

{
  "mcpServers": {
    "validationapp": {
      "type": "http",
      "url": "https://validationapp.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${VALIDATIONAPP_API_KEY}"
      }
    }
  }
}

Windsurf

In Cascade MCP settings, add a remote HTTP server with the same url and Authorization header.

Other HTTP MCP clients

If your tool supports remote Streamable HTTP with custom headers, use the shared JSON config above. OAuth-only MCP marketplaces are not supported — ValidationApp uses API key Bearer auth.

Available tools

validate_email

Validate a single email address. Consumes credits.

email (required); deliverability_only or threat_only (optional booleans)

upload_email_list

Upload a CSV email list for batch validation.

filename; emails[] or csv

start_batch_validation

Start asynchronous batch validation on an uploaded list.

list_id; action (dt, dc, td, or evaluate)

get_job

Get validation job status and metadata.

job_id

search_job_results

Search paginated validation results for a completed job.

job_id; page; limit

download_job_results

Download job results as CSV text.

job_id; type (all, bestreach, maxreach); provider (optional)

get_credit_balance

Read remaining subscription and lifetime credit balances.

(none)

Typical batch workflow

  1. Call upload_email_list with a filename and emails[] or csv text.
  2. Call start_batch_validation with the returned list_id and action dt, dc, or td.
  3. Poll get_job until the job status is complete.
  4. Use search_job_results for paginated rows or download_job_results for CSV export.
  5. Call get_credit_balance anytime to check remaining subscription and lifetime credits.

Prefer raw HTTP? See the API reference.