MCP Server

CampaignKit provides a Model Context Protocol (MCP) server that enables AI assistants and Large Language Models (LLMs) to validate email addresses programmatically. The MCP server exposes CampaignKit’s email validation capabilities through a standardized protocol that works with Claude, custom AI applications, and any MCP-compatible client.

What is MCP?

The Model Context Protocol (MCP) is an open standard that enables AI assistants to securely connect to external data sources and tools. Think of it as an API specifically designed for AI interactions—allowing LLMs to fetch data, perform actions, and integrate with services in a controlled, secure manner.

CampaignKit’s MCP server allows AI assistants to:

• Validate email addresses in real-time
• Process batch validation jobs
• Retrieve validation results and statistics
• Access your validation history

Architecture

Protocol Specification

• Protocol: MCP 2024-11-05
• Transport: Server-Sent Events (SSE) over HTTPS
• Message Format: JSON-RPC 2.0
• Endpoint: https://api.campaignkit.cc/v1/mcp/sse
• Discovery: https://api.campaignkit.cc/v1/mcp/.well-known/oauth-server-metadata

How It Works

┌─────────────┐
│ AI Client   │ (Claude, custom app, etc.)
│ (MCP Client)│
└──────┬──────┘
       │ 1. Discovers server capabilities
       │ 2. Authenticates with API key
       │ 3. Calls validation tools
       ▼
┌────────────────────────────┐
│ CampaignKit MCP Server     │
│ (JSON-RPC over SSE)        │
└──────┬─────────────────────┘
       │ 4. Validates emails
       │ 5. Returns results
       ▼
┌────────────────────────────┐
│ Email Validation Engine    │
│ (Multi-stage verification) │
└────────────────────────────┘

The MCP server uses Server-Sent Events (SSE) for transport, which allows:

• Real-time streaming responses
• Long-lived connections
• Efficient bidirectional communication
• Standard HTTP/HTTPS (works through firewalls)

Authentication

API Key Authentication

The MCP server authenticates requests using your CampaignKit API key passed as a Bearer token.

Header Format:

Authorization: Bearer YOUR_API_KEY

Get Your API Key:

1. Sign in to CampaignKit
2. Navigate to Settings → API Keys
3. Click Create New API Key
4. Copy the generated key (format: ck_...)

Configuration Example

For MCP clients (like Claude Desktop):

{
  "mcpServers": {
    "campaignkit": {
      "url": "https://api.campaignkit.cc/v1/mcp/sse",
      "headers": {
        "Authorization": "Bearer ck_your_api_key_here"
      }
    }
  }
}

Available Tools

The MCP server exposes 5 tools for email validation:

1. validate_email

Validates a single email address immediately with comprehensive checks.

Parameters:

Example Request:

{
  "name": "validate_email",
  "arguments": {
    "email": "john.doe@example.com"
  }
}

Response:

{
  "email": "john.doe@example.com",
  "score": 10,
  "classifier": "valid",
  "syntax": "pass",
  "mx": "pass",
  "mailbox": "pass",
  "description": ["syntax", "domain", "mailbox"],
  "smtp_response": "250 OK"
}

Credits: 1 credit per validation

2. create_validation_job

Creates an asynchronous batch validation job for multiple email addresses.

Parameters:

Example Request:

{
  "name": "create_validation_job",
  "arguments": {
    "emails": [
      "alice@example.com",
      "bob@test.com",
      "charlie@domain.org"
    ],
    "label": "Q1 Lead List"
  }
}

Response:

{
  "job_id": 123,
  "label": "Q1 Lead List",
  "state": "pending",
  "email_count": 3,
  "message": "Validation job created successfully. Use get_job_status with job_id=123 to check progress."
}

Credits: 1 credit per email (charged during processing)

3. get_job_status

Retrieves the current status and summary of a validation job.

Parameters:

Example Request:

{
  "name": "get_job_status",
  "arguments": {
    "job_id": 123
  }
}

Response:

{
  "job_id": 123,
  "label": "Q1 Lead List",
  "state": "done",
  "email_count": 3,
  "source": "mcp",
  "summary": {
    "totalEmails": 3,
    "uniqueEmailsCount": 3,
    "deliverableCount": 2,
    "undeliverableCount": 1,
    "riskyCount": 0
  }
}

Job States:

• pending - Queued for processing
• running - Currently being processed
• done - Completed successfully
• failed - Processing failed
• paused - Job paused

Credits: None (status check is free)

4. get_job_results

Retrieves paginated validation results from a completed job.

Parameters:

Example Request:

{
  "name": "get_job_results",
  "arguments": {
    "job_id": 123,
    "page": 1
  }
}

Response:

{
  "job_id": 123,
  "page": 1,
  "count": 3,
  "results": [
    {
      "email": "alice@example.com",
      "score": 10,
      "classifier": "valid",
      "syntax": "pass",
      "mx": "pass",
      "mailbox": "pass"
    },
    {
      "email": "bob@test.com",
      "score": 0,
      "classifier": "invalid",
      "syntax": "pass",
      "mx": "fail",
      "mailbox": "n/a"
    }
  ],
  "summary": { ... }
}

Credits: None (retrieving results is free)

5. get_validation_stats

Retrieves validation statistics and history for your account.

Parameters:

Example Request:

{
  "name": "get_validation_stats",
  "arguments": {
    "days": 30
  }
}

Response:

{
  "period_days": 30,
  "total_validations": 1247,
  "valid_count": 1089,
  "invalid_count": 98,
  "risky_count": 60,
  "blacklisted_count": 15,
  "valid_percentage": "87.3%",
  "invalid_percentage": "7.9%",
  "risky_percentage": "4.8%",
  "breakdown_by_day": [...]
}

Credits: None (statistics are free)

Validation Results

Score System

Email addresses receive a score from 0 to 10:

Classifiers

Every email receives one of three classifications:

Check Results

Each validation performs multiple checks:

Syntax Check (pass / fail)

• Validates email format against RFC 5322
• Checks for common typos and formatting issues

MX Check (pass / fail)

• Verifies domain has mail exchange records
• Confirms domain can receive email

Mailbox Check (pass / fail / n/a)

• Attempts SMTP handshake to verify mailbox exists
• Returns n/a if verification cannot be completed (e.g., catch-all domains)

Description Flags

Additional details about the email address:

• syntax - Email syntax is valid
• domain - Domain exists and has MX records
• mailbox - Mailbox exists and can receive email
• verifyRejected - SMTP verification was rejected
• blacklist - Email is on internal blacklist
• disposable - Disposable/temporary email service
• role - Role-based email (info@, support@, sales@, etc.)
• catchAll - Domain accepts all email addresses

Error Handling

The MCP server returns standard JSON-RPC 2.0 error responses:

Common Errors

Application Errors

Insufficient Credits:

{
  "error": "insufficient credits: available=5, required=10"
}

Solution: Purchase additional credits at app.campaignkit.cc/plans

Job Not Found:

{
  "error": "job not found"
}

Solution: Verify job ID is correct and belongs to your account

Invalid Email Format:

{
  "error": "email parameter is required and must be a string"
}

Solution: Ensure email parameter is provided as a string

Rate Limits & Billing

Credits

• Each email validation costs 1 credit
• Credits are only charged for emails with valid syntax
• Failed syntax checks consume no credits
• Checking job status and retrieving results is free

Rate Limits

• API Key Authentication: No hard rate limits, governed by credit availability
• Concurrent Jobs: No limit on number of active jobs
• Batch Size: No hard limit per job (but consider credit availability)

Pricing

• Free Tier: 25 validations when you sign up
• Pay-as-you-go: Purchase credits as needed
• Subscription Plans: Monthly credits with volume discounts

View current pricing at campaignkit.cc/pricing

Security Best Practices

API Key Management

1. Never Share Keys - Treat API keys like passwords
2. Use Environment Variables - Don’t hardcode keys in code
3. Rotate Regularly - Generate new keys periodically
4. Revoke Compromised Keys - Delete and replace immediately
5. Monitor Usage - Review validation history for suspicious activity

Secure Configuration

# Good: Environment variable
export CAMPAIGNKIT_API_KEY="ck_your_key_here"
 
# Bad: Hardcoded in code
const apiKey = "ck_your_key_here"; // DON'T DO THIS
 
# Bad: Committed to git
config.json with API key // DON'T DO THIS

Access Control

• Each API key is scoped to one account
• Validation results are isolated per account
• Jobs and statistics are account-specific
• No cross-account data access

Use Cases

AI-Powered Email Validation

Use Claude or other AI assistants to validate emails during conversations:

• Customer support: Verify customer email addresses
• Sales: Validate leads before outreach
• Research: Check contact information quality

Automated List Cleaning

Integrate MCP into automated workflows:

• Batch validate imported lists
• Clean CRM data periodically
• Verify form submissions in real-time

Custom AI Applications

Build custom applications with MCP:

• Email validation chatbots
• Lead scoring systems
• Data quality dashboards
• Automated email verification tools

MCP Client Support

The CampaignKit MCP server works with:

• Claude Desktop - Anthropic’s desktop application (Setup Guide)
• Claude.ai - Web-based Claude interface
• Custom MCP Clients - Any application implementing MCP protocol
• AI Development Frameworks - LangChain, AutoGPT, etc. (with MCP support)

Technical Specifications

Protocol Details

Protocol: MCP 2024-11-05
Transport: Server-Sent Events (SSE)
Message Format: JSON-RPC 2.0
Content-Type: text/event-stream

Server Capabilities

{
  "protocolVersion": "2024-11-05",
  "capabilities": {
    "tools": {}
  },
  "serverInfo": {
    "name": "campaignkit-email-validator",
    "version": "1.0.0"
  }
}

Endpoint Information

Additional Resources

• Claude AI Integration Guide - Setup instructions for Claude
• API Documentation - REST API reference
• Email Validation Guide - Best practices and articles
• MCP Protocol Specification - Official MCP documentation

Need help with the MCP server? Contact us through the chat widget or email support@campaignkit.cc.