Using Validation App MCP in Cursor and Claude Code

If you use Cursor, Claude Code, or another MCP-capable assistant, you can validate emails and run list jobs without leaving the editor—no local npm package, no custom scripts. Validation App hosts a customer email validation MCP server at /api/mcp that speaks the same API key auth as the REST API.

This guide walks through what the MCP server does, how to connect Cursor and Claude Code, which tools are available, and a typical batch workflow. For copy-paste JSON configs and client-specific notes, see the full MCP setup docs.

What the email validation MCP server does

Model Context Protocol (MCP) lets AI tools call structured functions on your behalf. Validation App’s hosted MCP server exposes validation operations your assistant can invoke with natural language—single checks, CSV uploads, batch jobs, result exports, and credit balance reads.

It runs on the same host as the REST API using Streamable HTTP (POST /api/mcp and GET /api/mcp). You authenticate with a live API key from Dashboard → API Keys—the same va_live_… key you use for HTTP, sent as Authorization: Bearer … or X-API-Key.

This is the customer MCP for validation workflows. It is not the internal admin MCP used for CMS operations—keep admin keys separate if your organization uses them.

Before you connect: get an API key

1. Sign in to Validation App and open API Keys in the dashboard.
2. Generate a live key (va_live_…) with validation scope.
3. Copy the key once—it is shown at creation time. Rotate anytime from the same screen.
4. Confirm the key is enabled; disabled keys return HTTP 401 from MCP.

Prefer environment variables over hardcoding keys in config files you commit to git. Most MCP clients support header placeholders such as ${VALIDATIONAPP_API_KEY}.

Connect Cursor

In Cursor, add a remote MCP server pointing at your API base URL plus /api/mcp. Production example:

URL: https://validationapp.com/api/mcp

Header: Authorization: Bearer va_live_xxxxxxxx (replace with your key)

Cursor accepts a JSON block under MCP settings with mcpServers.validationapp.url and headers.Authorization. After saving, open the MCP tools panel and confirm the server connects without 401 errors.

Full Cursor JSON example: MCP setup docs → Cursor.

Connect Claude Code

Claude Code supports HTTP MCP via CLI or project config (.mcp.json / ~/.claude.json).

CLI one-liner (with your key in an env var):

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

Run /mcp in a session to verify the connection. Use "type": "http" or "streamable-http" in JSON config—the docs page shows the shared HTTP shape.

Other clients (VS Code, Windsurf, generic HTTP)

Any MCP client that supports remote Streamable HTTP with custom headers can use the same URL and Bearer auth:

• VS Code + Copilot — add .vscode/mcp.json with "type": "http", your /api/mcp URL, and Bearer header.
• Windsurf — add a remote HTTP server in Cascade MCP settings with the same URL and header.
• OAuth-only marketplaces — not supported; Validation App uses API key Bearer auth only.

See /docs/mcp for the shared JSON template.

Available MCP tools

Seven tools mirror common dashboard and API workflows:

• validate_email — single-address check (optional deliverability-only or threat-only flags). Consumes credits.
• upload_email_list — upload a CSV or email array for batch processing.
• start_batch_validation — start async validation on an uploaded list; action dt, dc, td, or evaluate.
• get_job — poll job status until complete.
• search_job_results — paginated rows for a finished job.
• download_job_results — export CSV text (all, bestreach, or maxreach; optional provider filter).
• get_credit_balance — read subscription and lifetime credit balances.

Tool argument details live on the MCP docs page. Prefer raw HTTP? Use the REST API reference instead.

Typical batch workflow from your assistant

Ask your assistant to follow this sequence when cleaning a list via MCP:

1. upload_email_list — pass a filename and emails[] or CSV text.
2. start_batch_validation — pass the returned list_id and an action (dt for full deliverability + threat, dc deliverability-only, td threat-only).
3. get_job — poll until status is complete.
4. search_job_results or download_job_results — review rows or export a segment CSV.
5. get_credit_balance — check remaining credits anytime during the run.

Example prompt: “Upload this CSV, run deliverability validation, and download the best-reach segment when the job finishes.”

Tips and limits

• Credits — MCP calls consume the same credits as REST; preview/evaluate behavior matches dashboard rules.
• Stage vs production — point the URL at your stage host if you are testing; path stays /api/mcp.
• Security — treat MCP keys like production secrets; rotate after sharing a machine or repo.
• No local install — the server is hosted; you only configure the client.

Where to go next

• Full client configs and tool tables: MCP setup documentation
• HTTP endpoints and response shapes: API reference
• Dashboard list workflow (upload → preview → clean): free list preview or Bulk Scans after sign-in

Ready to connect? Generate an API key, paste the config from /docs/mcp, and ask your assistant to validate a test address.