MCP Server · v1

Model Context Protocol

Connect Claude, Cursor, VS Code, and any MCP-compatible agent to ValidPeak's email validation and campaign intelligence tools — no SDK required.

Streamable HTTP

JSON-RPC 2.0

VP-Api-Key Auth

6 Tools

Connection

Same VP-Api-Key header used by every other ValidPeak API endpoint. Rate-limiting and usage metering apply per organization.

Property	Value
Transport	`HTTP (Streamable HTTP, MCP spec §4.2)`
Endpoint	`https://<host>/api/v1/mcp`
Protocol	`JSON-RPC 2.0`
Auth header	`VP-Api-Key: <your-api-key>`

Client configuration

Claude Desktop

VS Code / Cursor

Tool Discovery

json — claude_desktop_config.json

{
  "mcpServers": {
    "validpeak": {
      "url": "https://<host>/api/v1/mcp",
      "headers": {
        "VP-Api-Key": "<your-api-key>"
      }
    }
  }
}

Authentication & Scopes

Every API key carries scopes that control which tools are accessible. Missing scope errors return a clear message rather than a generic 403.

Scope	Grants access to
email_validation	`validate_single_emaillist_bulk_validation_jobs`
campaign_read	`list_campaign_domainsget_campaign_send_ruleget_recent_blocked_send_attemptsget_campaign_esp_link`

Tools Reference

Six tools across two scopes. Expand any tool to see its parameter schema, response shape, and JSON-RPC call example.

Validates a single email address in real time and returns its deliverability verdict. Use this to check whether an address is safe to send to before adding it to a list or campaign.

Parameters

Name	Type	Required	Description
`email`	`string`	required	The email address to validate

Response & Example

Response shape

JSON-RPC example

json

{
  "email": "jane.doe@example.com",
  "normalized_email": "jane.doe@example.com",
  "did_you_mean": null,
  "status": "deliverable",
  "sub_status": "unknown",
  "score": 92,
  "score_label": "High",
  "is_deliverable": true,
  "is_disposable": false,
  "is_role_address": false,
  "is_catch_all": false,
  "is_free_provider": false,
  "smtp_provider": "Google"
}

Lists bulk email validation jobs for the organization, newest first. Use this to check the progress or results of a bulk list-cleaning job.

Parameters

Name	Type	Required	Description
`status`	`string`	optional	Filter by state: queued \| processing \| completed \| failed
`since`	`string (ISO-8601)`	optional	Only return jobs created after this timestamp
`limit`	`integer`	optional	Max jobs to return (1–100). Default: 25

Response & Example

Response shape

JSON-RPC example

json

{
  "total": 14,
  "has_more": false,
  "jobs": [{
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "June Newsletter List",
    "state": "completed",
    "total_emails": 8500,
    "deliverable": 7140,
    "undeliverable": 680,
    "risky": 420,
    "unknown": 210,
    "duplicated": 50,
    "created_at": "2026-06-01T10:00:00Z"
  }]
}

Lists the campaign domains registered for the organization. Call this first to obtain campaign_domain_id values required by the other campaign tools.

Parameters

Parametersnone required

Response & Example

Response shape

JSON-RPC example

json

[{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "domain": "newsletters.example.com",
  "display_name": "Example Newsletters",
  "analysis_status": "Analyzed",
  "last_analyzed_at": "2026-06-08T14:30:00Z",
  "email_source_esp_type": "Mailchimp"
}]

Returns the active Send Engine rule for a campaign domain — the deliverability score threshold below which sends are automatically blocked.

Parameters

Name	Type	Required	Description
`campaignDomainId`	`string (UUID)`	required	Campaign domain ID from list_campaign_domains

Response & Example

Response shape

JSON-RPC example

json

{
  "id": "7b8e9f10-1234-5678-abcd-ef1234567890",
  "score_threshold": 70,
  "send_mode": "Immediate",
  "scheduled_at": null,
  "is_active": true,
  "created_at": "2026-03-01T08:00:00Z",
  "updated_at": "2026-06-05T11:20:00Z"
}

Lists recent sends blocked by the Send Engine because the domain's score fell below its threshold. Useful for diagnosing why a campaign didn't go out.

Parameters

Name	Type	Required	Description
`since`	`string (ISO-8601)`	optional	Only return attempts blocked after this timestamp
`limit`	`integer`	optional	Max attempts to return (1–25). Default: 25

Response & Example

Response shape

JSON-RPC example

json

[{
  "id": "a1b2c3d4-0000-0000-0000-000000000001",
  "campaign_domain_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "blocked_at": "2026-06-07T09:15:00Z",
  "score_at_attempt": 58,
  "error_message": "Score 58 is below the configured threshold of 70."
}]

Returns the ESP campaign linked to a campaign domain's Send Engine — which campaign will be evaluated and sent, its subject, from-address, and estimated recipient count.

Parameters

Name	Type	Required	Description
`campaignDomainId`	`string (UUID)`	required	Campaign domain ID from list_campaign_domains

Response & Example

Response shape

JSON-RPC example

json

{
  "id": "f9e8d7c6-5432-10ab-cdef-fedcba987654",
  "esp_type": "Mailchimp",
  "esp_campaign_name": "June Newsletter",
  "esp_campaign_subject": "Your June update is here",
  "esp_from_email": "newsletters@example.com",
  "estimated_recipients": 8200,
  "linked_at": "2026-06-06T16:00:00Z"
}

Error Handling

MCP errors are returned inside the result.content array with isError: true — not as JSON-RPC error objects.

error response shape

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [{
      "type": "text",
      "text": "This API key does not have the required scope: 'campaign_read'."
    }],
    "isError": true
  }
}

Error message	Cause
`This API key does not have the required scope: '<scope>'.`	Key missing required scope
`Could not resolve an organization from the authenticated API key.`	Key is malformed or revoked
`Email is required.`	Empty string passed to validate_single_email
`No active send rule found for this campaign domain.`	Domain has no Send Engine rule configured
`No ESP campaign linked to this campaign domain.`	No campaign linked to Send Engine

Recommended Workflow

A complete demo of the Send Engine flow — from listing domains to validating a sample email.

list_campaign_domains

Get all registered campaign domains and pick a domain_id.

get_campaign_send_rule

Retrieve the active rule — note the score_threshold that blocks sends.

get_campaign_esp_link

See which ESP campaign is queued and its estimated recipient count.

get_recent_blocked_send_attempts

Explain why past sends were blocked with score and error details.

validate_single_email

Run a real-time check on a sample address to demonstrate live validation.

Not exposed in v1 (by design)

The following mutations require human confirmation and are intentionally excluded from the MCP surface: configure / update a Send Engine rule · link / unlink an ESP campaign · trigger a campaign send · manage integrations or API keys. These are available via the ValidPeak REST API for n8n, Make, and Zapier automation workflows.

Model Context Protocol

Connection

Authentication & Scopes

Tools Reference

validate_single_emailemail_validationValidates a single email address in real time and returns its deliverability verdict. Use this to check whether an address is safe to send to before adding it to a list or campaign.

list_bulk_validation_jobsemail_validationLists bulk email validation jobs for the organization, newest first. Use this to check the progress or results of a bulk list-cleaning job.

list_campaign_domainscampaign_readLists the campaign domains registered for the organization. Call this first to obtain campaign_domain_id values required by the other campaign tools.

get_campaign_send_rulecampaign_readReturns the active Send Engine rule for a campaign domain — the deliverability score threshold below which sends are automatically blocked.

get_recent_blocked_send_attemptscampaign_readLists recent sends blocked by the Send Engine because the domain's score fell below its threshold. Useful for diagnosing why a campaign didn't go out.

get_campaign_esp_linkcampaign_readReturns the ESP campaign linked to a campaign domain's Send Engine — which campaign will be evaluated and sent, its subject, from-address, and estimated recipient count.

Error Handling

Recommended Workflow